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:
Step 1: Heading 2 StyleÂ
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
Â