On this page
- Before you add a new documentation page
- How to suggest documentation
- Basic document structure
- Style guidelines
- To add a new documentation page
In order to insure users have a consistent experience throughout the Open Atrium documentation, we ask that you follow a few simple guidelines. Once you've created an account, you'll be able to edit most documentation pages. To see how they are formatted, just click the Edit tab and view the source of the body. This can be a great way to see what other people have done, or you can copy content and use it as a template for your own page.
Before suggesting or adding to documentation, it's good to make sure that that page doesn't exist already and that the documentation is the right place to put it.
- First, use the in-site search for keywords that would be likely matches for what you'd like to add
- Is your post requesting support? If so, then the issue tracker is a better place to post.
- Finally, review the documentation structure to determine where your new page would best fit
If you are able to write the documentation yourself, then finish reading this guide and leap right into adding it in. If you're not able to write the documentation soon, then you should create an issue in the issue tracker group to suggest the documentation. Here's how:
- Go to https://community.openatrium.com/issues/.
- Click the Add Case button.
- Select Documentation for the project.
- If you anticipate being able to write the documentation yourself at some point, assign the project to your user account, otherwise leave it unassigned.
- Set the Type to Task.
- Begin the title with Suggested doc:, along with a working title for the doc page.
- Fill in a description for the doc in the body input. Include any details you have available. Outlines are helpful to give an idea of the subject matter you would like to see covered.
There is only one required section to a document - the content - but there are some additional sections you can add to enrich the page:
- On this page - If the document page is long, you might want to add an index to allow people to jump to specific areas of the page. By adding sub-sections that can be linked to, other pages can also link to these sub-sections. See the internal linking section in the Markdown documentation for an example.
- Content - The main content of the page. No heading is needed, just leap right in.
- See also - The See also section contains links to related content, and should contain two sections, one for related resources on this site and one for external resources. Here is an example of the structure, in markdown:
h3tags for sub-headings in your documentation. If you find yourself wanting to use sub-sub headings, then your page would probably be a good candidate for a parent page with sub-pages.
- Use Markdown whenever possible to simplify reading and managing of the content.
- To indicate which menu trail a user should follow, begin with the trail in bold, and follow with the path without a preceding slash, enclosed in parentheses and code tags. For example: Administer > Site building > Modules
(admin/build/modules). In Markdown, this would be written like so:
__Administer > Site building > Modules__ `(admin/build/modules)`
There are two options for adding a new documentation page. First, if you would like to add a child page to the document you are currently viewing, scroll the bottom of the screen and click the Add child page link:
Alternatively, you can click the Add Book page button in the upper right-hand corner of the screen:
Fill out the form, following the guidelines below on document structure.
Make sure to select the right Book and Parent Item in the book under the Book outline section.
Click the Preview button to preview your page before posting it.
Once you're satisfied, click the Save button.