Documentation Style Guide

Brief introduction or overview paragraph to explain the objective of the topic should go here. Try to keep the documentation brief and easy to follow using the Step-By-Step approach. If you have lots and lots of technical background information to include, sometimes it works best to include this under the "Additional References" section or add links in your steps pointing to any lengthy overviews. The main objective to a manual page is to get adopters to successfully implement the steps through an ease of readability.

Use an Information section to give credit to contributor:

 Documentation contributed by John Doe from ABC University

Note sections should indicate if this piece of documentation is for a specific minor release of uPortal.

Step 1: Heading 2 Style 

Optional Note sections should be used to indicate if a step has any prerequisites, caveats, etc...

A brief paragraph of the individual step should be placed here if an explanation is necessary.

  • Bullets should be used for the process within each step
  • If a file needs to be edited, indicate the full file path in your process (ex., uPortal-4.x/uportal-war/src/main/resources/properties/security.properties)
  • Use a code block for a code snippet (file path in the title) or command. (see below)

    ant clean deploy-war

    or

    uPortal-4.x/filters/local.properties
    ## EXAMPLES ##
    ## HSQL Configuration
    environment.build.hsql.port=8887
    ## Database Connection Settings (Uncomment the Maven Filters section in rdbm.properties)
    environment.build.hibernate.connection.driver_class=org.hsqldb.jdbc.JDBCDriver
    environment.build.hibernate.connection.url=jdbc:hsqldb:hsql://localhost:${environment.build.hsql.port}/uPortal
    environment.build.hibernate.connection.username=sa
    environment.build.hibernate.connection.password=
    environment.build.hibernate.dialect=org.hibernate.dialect.HSQLDialect
    # uPortal server configuration properties
    environment.build.uportal.server=localhost:8080
    environment.build.uportal.protocol=http
    environment.build.uportal.context=/uPortal
    environment.build.uportal.email.fromAddress=portal@university.edu

Step 2: Heading 2 Style

If your step includes an action that needs a strong warning, such as the action will delete the table data, please use a warning section. (See example below)

Warning: Executing the command "ant clean initportal" will drop and recreate the database tables and all existing data will be lost. This will result in a clean uPortal database structure. If you want to keep the contents of your existing database, use "ant clean deploy-war"

  • Bullets should be used for the process within each step
  • Bullets should be used for the process within each step

Step 3: Heading 2 Style

A picture is worth a thousand words!

  • If an image is available to demonstrate the ending result or a particular step please insert the image here (see image below).

 

Step 4: Heading Style 2

Sometimes subtopics are warranted under a step which needs lots of explaining. However, try to split up the topic as best as you can so others can easily follow along.

Subtopic Heading Style 3

A brief paragraph of the individual step should be placed here if an explanation is necessary.

  • Bullets should be used for the process within each step
  • Bullets should be used for the process within each step
  • Use a code block for a code snippet (file path in the title) or command. (see below)
ant clean deploy-war

Subtopic Heading Style 3

A brief paragraph of the individual step should be placed here if an explanation is necessary.

  • Bullets should be used for the process within each step
  • Bullets should be used for the process within each step

 

Having problems with these instructions?

Please send us feedback at uportal-user@lists.ja-sig.org