Organizing Documentation

Creating a Page

Determine if you need to create a new page. Are there any pages that contain related information? Would the information you want to add serve the existing content better if it were placed in that page? Is the information you want to add supplemental, or entirely new? Also consider the titles of the pages in question. If you need to change the title of a page to add your information, is there a better way to add it?

In the event that you determine creating a new page is the best option, use the following tips to ensure a unified documentation experience.

Naming a Page

Page titles are defined by the name of the file. Dashes (minus signs) will be replaced by spaces by GitHub's wiki when displaying the title in the sidebar or above the page, and should be used instead of spaces. Try to keep the title as short but descriptive as possible.

(Note: You should add a .md extension if using git instead of the online GitHub interface.)

GOOD page names:

• Bash-Crash-Course
• Writing-Documentation
• Quick-Guide-to-Linux

Bad page names:

• quickguideforopeningfilesinwslvirtualized
  Why is this bad? - Use short names and put dashes between words.
• notes
  Why is this bad? - Use descriptive names.
• GitHub Crash Course
  Why is this bad? - Use dashes instead of spaces.

Linking the Page

Although the side bar displays every page in the wiki, it is important to put your page on the Wiki's Home page. Find a related page on the topic, and place your page in a logical position around it. Is your page more complicated than the other documents? Try to place it at the end of the other documents to indicate the increasing complexity.