Contributing to the OpenSim Documentation

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:

	Click the arrow to open the drop down menu Select the desired size and style of your text

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:

	Click the Link button in the toolbar which opens the screen shown on the left Make sure you are in the Search tab on the left Start typing the page you want to navigate to, and select the page from the suggestions prompted by the computer.

To navigate between sections of the same page:

Click the Link button in the toolbar Click the Advanced tab in the bar on the left as shown in the figure on the left To link between sections on the same page you need to have an Anchor marking the destination. To make an Anchor visit the Insert section. In the Link: textbox type the character "#" followed by the name of the Anchor In the Link Text: textbox enter the way you would like the user to see the link in the document. The name of the link and the way it appears can be different but for simplicity it is often the same.

Tables

To insert a table:

	Click the Table drop down menu to open the figure shown on left Move your mouse until the dimensions shown at the bottom match the desired dimensions Release the mouse and the table will insert where the mouse is in the document

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:

	Click the Insert button to access the drop down menu shown above Move your mouse until your highlighting the "Other Macros" tab at the bottom of the menu, as shown above When you release the mouse, the window on the left will appear listing all the macros Choose your desired macro and follow the prompts

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:

Choose "Table of Contents" from the Insert --> Other Macros window shown above The window on the left will open, in the preview side you see the table of contents as it currently appears The table of contents macro automatically makes a table of contents based on the headings from Paragraph Format All you have to do is click Insert 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:

	Choose "Anchor" from the Insert --> Other Macros window shown above The window on the left will open Type an appropriate name into the Anchor Name textbox Click Insert To link to an anchor, visit Links  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:

• http://www.codecogs.com/latex/eqneditor.php
• http://en.wikipedia.org/wiki/Help:Displaying_a_formula

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.