Help us improve and expand the OpenSim documentation! Once you create an account on confluence, you will be able to make edits to our documentation wiki. The site tracks contributors, so you will get credit for your efforts. Before you make changes please review our guidelines.
Documentation Guidelines and Style Guide
This section will cover two main topics regarding OpenSim documentation. Contributions made to this wiki should be in agreement with the Style Guidelines and if you're having trouble making the wiki do what you want it to, visit Tips For Editing.
Style Guidelines
DO's:
- Page Format
- Every page needs a title that is descriptive of the material contained in the page.
- If you're contributing multiple related pages they should be included in one overarching topic with links between pages for the reader's convenience.
- Every page should have a table of contents at the top of the page listing the topics on that page.
- Use tables to organize text and graphics appropriately.
- Use hyperlinks to help navigate your pages.
- Content
- Content should be relevant and readable.
- Content should be an unexplored topic in the documentation. If you are unsure if your desired topic has been covered previously, please email us at opensim@stanford.edu. If you have suggestions for how to improve an existing page, send those suggestions via email.
DON'T's:
- Page Format
- You shouldn't make a text only page with no headings within the pages and no graphics.
- You shouldn't try and make your page stand alone. Reference other existing pages in the wiki for clarity.
- Content
- You shouldn't create pages with unrelated topics
- You shouldn't make pages about your personal research. Information about how you're using OpenSim belongs in the user's forum or on your personal SimTK project page.
Tips For Editing
Editing Toolbar:
Paragraph Format
You may notice there is not text size option in the toolbar. The paragraph format changes the style and size of the text. To change the paragraph format:
|
---|
Text Style
This controls the style and color of your text. There is a lot of overlap with the text style and the paragraph format. If the text when typed appears bold and nothing happens when you click the bold button in the toolbar try using the Paragraph Format drop down menu to select a normal font text.
Bullet/Numbering
These are toggle buttons to turn bullet/numbering on and off. The default is for your text to be typed bold following a bullet or number. To type normal text following a bullet/number type out your text, highlight it, and use the Paragraph Format to reselect paragraph option.
Paragraph Indentation
There are two types of paragraph indentations. The left 2 buttons, are the equivalent of pressing tab in a word document. Because the wiki is an internet page the tab button with not indent the text. The left 3 buttons, control the indentation of the entire paragraph. You can set it to align on the left, the right, or center it.
Links
There are two main types of links. There are link that move between pages and there are links that navigate to a different section of the same page. To make links between pages:
|
---|
To navigate between sections of the same page:
|
---|
Tables
To insert a table:
|
---|
Insert
The Insert button has many functions, many of which are common to most word document insert options.
The options discussed here will be the options that are unique to the wiki page format. The wiki has elements called "Macros." These macros are the aspects of the document that allow for navigating between sections on the same page, (making anchors) inserting a table of contents, an info or note textbox, and many more.
To insert a macro into your wiki:
|
---|
Feel free to explore all the macros and the qualities they offer. This page will only discuss the macros necessary to be in compliance with our guidelines.
To insert a table of contents:
If you made a new heading and it doesn't appear in the table of contents, save the page and then click edit and insert the table of contents after the document has been saved with the new heading in the page.
|
---|
To insert an anchor:
While you are editing a page the Anchors that exist will appear in a gray box next to the text they mark. When you save the page these gray boxes will disappear but the links will still be there.
|
---|
Undo/Redo
These buttons undo and redo previous mistakes within one editing session of a page. Once a page has been saved, the undo and redo buttons will not have a record of changes made during previous editing sessions.
Equations
You can insert equations that use LaTeX markup using the Math Formula macro. For example, you can create this formula:
by choosing Insert -> Other Macros -> Formatting -> Math Formula (or search for Math Formula). Then enter the following in the Math Formula macro box:
\left(\, \sum_{k=1}^n a_k b_k \right)^2 \le \left(\, \sum_{k=1}^n a_k^2 \right) \left(\, \sum_{k=1}^n b_k^2 \right)
The following links might be helpful if you are new to LaTeX:
Equations may render differently when the page is previewed, so be sure to check them again upon saving.
Things to Do
There is a list of items that we know need work in the Documentation To Do List.
Video Ideas
You can also contribute tutorial videos. See the existing tutorials or your YouTube channel for examples. See some ideas in the Documentation To Do List.