Documentation written for the public HySDS wiki uses a conversational tone, though not at the expense of utility or clarity.

Wiki documentation can assume a baseline technical background of your audience. Foundational computing concepts normally covered in a four year university education do not need to be explained. However, specific use cases or adaptations of technologies may require some contextualization. Most HySDS wiki readers hold at least a bachelor’s degree in a technical field, and have 1-2 years of related work experience.

Avoid unnecessary technical jargon, excessive use of JPL specific acronyms, ambiguous terms, and buzzwords. Your writing should be clear and specific while maintaining a brisk pace.

When context or explanation is necessary, provide it using full and natural sentences. Do not present information in code-like fragments of text; utilize complete sentences and thoughts.

Screenshots communicate valuable visual context to the user. If your documentation requires navigating a GUI at any point, screenshots will be an essential part of your documentation. All screenshots should be annotated for specific actions a user takes while proceeding. {be aware of screen load time and too many screenshots…hard to notice text between} {put them into expands!! this lets us see the high level overview}

All IP addresses should be cropped our or digitally blurred. No images from JPL internal resources should be shared on the public wiki.

Code helps guide the user through critical steps in your documentation. All code should use proper code markdown. All code should be displayed exactly as it is run, so the use can copy/paste it into their workflow.

TODO: how do you see command

Diagrams provide a visual map to quickly understand how various concepts interface. Not everything should be represented in a diagram however. If users have difficulty immediately understanding it, or have many follow-up questions, then the diagram probably isn’t suitable.

SME’s are JPL employees deemed highly knowledgeable about each page’s subject matter. A page can only have one SME. They are responsible for error checking on that page and are a good resource for questions on the topics covered. Often, but not always, the original author of new documentation will be the SME for that page. (the one’s that designed the technology or did most of the work, but not necessarily the one to maintain the page)

Page labels are another important navigation and usability feature of the HySDS wiki. Labels are used to populate the “Related Articles” box in each page’s footer. They are also used to identify documentation gaps, and perform wiki maintenance. It is your responsibility to properly label your documentation. More info on {Doc Start Here Page}

Someone willing/able to check page to ensure its still current. Doesn’t necessarily need to be the most knowledgable on the topic.

Information with multiple parameters should be displayed in a table format. Each column should be intuitively labeled and tables should fill the width of the page for optimal readability.

Several document templates are provided for you in the {Doc Start Here Page}. They minimize much of the work needed to generate consistent, organized wiki documents. Templates are categorized by documentation type: Tutorials, How-To Guides, Cheat Sheets, Reference. Be sure you are clear which category your documentation occupies.

Headings are important for the navigation, readability, and consistency of the wiki. The “Page Navigation” box on each page is populated by the heading hierarchy on that page. “Heading 1” should be used for the main concepts of your document. “Heading 2” should introduce sub-topics within each main concept. Use black font only.

For example: on this page “Voice,” “Elements,” and “Styling” all use “Heading 1” and each sub-topic is marked using “Heading 2.”