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 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 are helpful in certain situations. They 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 knowledgeable on the topic.

hysds_setup

needs_sme

needs_pm

step_by_step_guides

sme_assigned

pm_assigned

reference

update_sme

update_pm

cheatsheets

development

aws

tosca

hysds_setup

linux

figaro

operations_manual

python

mozart

diagram

elasticsearch

factotum

onboarding

kibana

verdi

troubleshooting

logstash

grq

version_3.0

rabbitmq

job_management

Version_2.0

celery

tasks

version_1.0

supervisord

workers

wiki_development

jenkins

sdswatch

docker

pge

github

provenance

terraform

metrics

sciflo

chimera

json

tasks

api

pleiades

ports

pcm

azure

yaml