Overview

This article describes the various types of documentation included in the HySDS wiki, and guidelines for creating additional documents following the best practices outlined below.

Page Navigation:

Page Navigation:

Who is Your Intended Audience?

First ask how knowledgeable your target audience is? The answer to this question will help direct you to the most appropriate documentation format.

A true beginner: they can’t formulate specific questions yet → Tutorial
Infrequent or new user: have enough knowledge to ask a specific question → Step-by-Step Guides
Regular user who needs targeted information → Cheat Sheets (Reference)
Regular user looking for context or background information → Discussions (Stack Overflow)

Source: https://www.youtube.com/watch?v=t4vKPhjcMZg&feature=youtu.be

Step-by-Step Guides (Problem-Oriented)

Step-by-Step Guides that the reader through a series of steps required to solve a common problem.

Elements of a Step-by-Step Guide

Section	Contains	Examples
Audience	The user has enough knowledge that they can ask meaningful questions. Answers to questions that a true beginner might not be able to formulate themselves.
Scope & Level of Detail	Recipes, or directions, to achieve some specific end. Enough flexibility that users can see how this can be applied to a slightly different case. Needs to be reliable, but doesn’t need to be bullet-proof. Goal focused. Only include steps needed to get to that goal. Addressing a specific question. Don’t need to explain things.	“How to create a ___”
Title & Description	Good naming is important, put effort into descriptive titles. Describe the problems that users can solve with this document	“Create, Edit, & Delete Trigger Rules” “Submit an On-Demand Job in Facet Search”
Formatting	Contains a list of steps that need to be followed in order to get to some end A series of practical steps (same as Tutorials)	Step 1: Do this. Step 2: Now do that.

Voice and tone

Enough openness that user can see how this can be applied to a slightly different case. Practical usability is more important than completeness.

Writing principles 

Start at the beginning. Begin the documentation at a reasonable starting point

Do

Achieve some practical goal that solves the user’s problem

Do 

Provide unnecessary explanations or extra details

Do n’t

A Little Flexibility

Step-by-Step Guides provide a user with guided directions on how to achieve a specific outcome. However, some flexibility is OK; a user should be able to see how to apply these steps to another similar situation.

Good Naming

Both the title of the document, and each step listed should describe the actions taken within them. Give the user a preview of what they will accomplish in each step with good naming.

Tips and tricks 

Most useful when doing the work/coding (same as Reference)

Cheat Sheets (Information-Oriented)

Cheat Sheets (Reference) gives users technical descriptions of the machinery and how to operate it. They only have one job: description.

Elements of a Cheat Sheet

Section	Contains	Examples
Audience	A regular user Cheat sheets are most useful when a user is doing the work.	HySDS Ops Team
Scope & Level of Detail	Don’t explain how to achieve common tasks. (Step-by-Step Guides do this) Just tells you about the topic, not what to do with it. Cheat sheets are information oriented. Don’t explain basic concepts.	HySDS GUI Overview
Title & Description	Summarize what subject is being referenced within	“HySDS Log File Overview” “HySDS GUI Overview”
Formatting	Should list and describe things. Cheat Sheets should be structured and consistent.	See Cheat Sheet Template
Declaration & Syntax	Code determined, this is ultimately what they’re describing.

Voice and tone

Austere and to the point. Cheat sheets are direct and lack unnecessary context or explanations.

Austere and to the point. Cheat sheets are direct and lack unnecessary context or explanations.

Writing principles 

Structure

Structure is formulaic and consistent. If appropriate, provide the user with a table to quickly access information. Reference material should have the same structure as the code base.

Explain basic concepts in reference guides

Don't 

Just give reader the facts (include examples if its useful)

Do 

Consistency

Language, tone, and structure are as consistent as possible. Eg a dictionary.

Description

Only job is to describe things clearly and completely. Anything else is a distraction.

Accuracy

Reference material is prone to deprecation. Documentation should clearly note when the information was last confirmed for accuracy.

Tips and tricks 

Most useful when doing the work/coding (same as Step-by-Step)

Tutorials (Learning-Oriented)

Lessons that take the reader by hand through a series of steps to complete a project. they show a beginner how to achieve something meaningful. The point of a tutorial is to get your learner started.

Elements of a Tutorial

Section	Contains	Examples
Audience	A true beginner
Scope & Level of Detail	A series of practical steps (same as Step-by-Step Guides) Most useful when we’re studying (same as Discussions) You decide for the learner what it is they should be learning Need to be bullet-proof
Title & Description	Summarize what subject is being referenced within
Formatting	No distractions Cheat Sheets should be structured and consistent.
Declaration & Syntax	Practical (not theoretical) knowledge
Parameters
Example

Voice and tone

Tutorials are informative. They guide a true beginner through a series of steps for the purpose of learning. They provide context, explanation, and are bullet-proof.

Tutorials are informative. They guide a true beginner through a series of steps for the purpose of learning. They provide context, explanation, and are bullet-proof.

Writing principles 

Inspire Confidence

The goal of a tutorial is to provider learners with the tools and knowledge to do a specific task. A successful tutorial will turn your learned into a user.

Learning by Doing

Tutorials should create a learning opportunity for the reader. Explanations should support a specific outcome which builds confidence.

Provide any explanations that don’t absolutely need to be explained

Don't 

Create an immediate sense of achievement

Do 

Concrete, not abstract

Tutorials deal with the particular not the general; they’re built around specific outcomes.

Repeatability

A reader should be able to recreate the outcomes of the tutorial on their own.

Tips and tricks 

Tutorials are designed to get new users started with the technology. Ideal topics are those which provide a strong foundation for deeper understanding of the material.

Discussions (Understanding-Oriented)

Explanations that clarify and illuminate a particular topic. This material will live mainly at Stack Overflow.

Elements of a Tutorial

Section	Contains	Examples
Audience	Both regular users and true beginners
Scope & Level of Detail	Background information on a topic Takes a wider view, steps away from the code Gives context, explains why No instruction or technical description
Title & Description	Titles should be descriptive and reflect a question being asked
Formatting	Multiple examples, alternative approaches
Declaration & Syntax
Parameters
Example

Voice and tone

Discussion material should be conversational yet specific. They provide a high-level overview of concepts, or specific details to troubleshoot issues.

Discussion material should be conversational yet specific. They provide a high-level overview of concepts, or specific details to troubleshoot issues.

Writing principles 

Making Connections

Good discussion responses help a user fill knowledge gaps and make broader connections about how a component fits into the broader whole.

Provide additional details beyond what is needed to learn and resolve a problem

Don't 

Use technical descriptions. Maintain a casual voice meant to help a user understand.

Don't 

Offer high-level context for general understanding if appropriate

Do 

Understanding Oriented

The purpose of discussion posts are to help a user understanding a specific problem or concept.

Tips and tricks 

Most useful when we’re studying (same as Tutorials)

Page Navigation:

Page Navigation:

Style Guide

This section provides an overview of the styling for wiki documentation. The goal of this guide is to provide a useful reference while creating new documentation while standardizing the wiki’s content.

Voice

Tone	Documentation written for the public HySDS wiki uses a conversational tone, though not at the expense of utility or clarity.
Audience	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.
Clarity	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.
Sentences	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.

Page Elements

Screenshots	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	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.
Diagrams	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	Subject Matter Experts are JPL employees deemed highly knowledgeable about each page’s subject matter. They are a good resource for questions on the topic. Often, but not always, the original author of new documentation will be the SME for that page.
Labels	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.
Page Maintainers	A designated point of contact responsible for maintaining the format and accuracy of a page. Doesn’t necessarily need to be the most knowledgeable person on the topic.
Tables	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.

Page Element Examples

Screenshots

Tips and tricks 

Sequential steps should be clearly numbered and associated with a button, text field, menu, etc.
Arrows should denote clickable elements
Rounded boxes highlight drop-down menus or text fields
If helpful, 1-2 words can be added to the screenshot for clarity. Eg “Click here”

Code

Tips and tricks 

All code should be presented in a copy and paste format for users
Large blocks of code need to use the “Expand” page macro and a “Code snippet” macro nested within it. See sample below
Large blocks of sample code syntax should follow the same requirements
Small code blocks (<5 lines) can be included directly onto the page using the “Code snippet” macro.
Multiple steps of code should each use the expand and code snippet macro. Users can expand each individually as they progress through the steps.

{
  "command": "string",
  "recommended-queues": [ "string" ],
  "disk_usage":"\d+(GB|MB|KB)",
  "imported_worker_files": {
    "string": "string",
    "string": [ "string" ],
    "string": [ "string", "ro" | "rw" ]
  },
  "dependency_images": [
    {
      "container_image_name": "string",
      "container_image_url": "string" | null,
      "container_mappings": {
        "string": "string",
        "string": [ "string" ],
        "string": [ "string", "ro" | "rw" ]
      }
    }
  ],
  "runtime_options": {
      "gpus": "string"
  },
"soft_time_limit": int, 
"time_limit": int, 
"disable_pre_builtins": true | false, 
"pre": [ "string" ], 
"disable_post_builtins": true | false, 
"post": [ "string" ], 
"params": [
{ "name": "string", "destination": "positional" | "localize" | "context" } 
]
}

{
  "command": "/home/ops/verdi/ops/hello_world/run_hello_world.sh",
  "recommended-queues": [ "factotum-job_worker-small" ],
  "disk_usage":"10MB",
  "imported_worker_files": {
    "$HOME/.netrc": ["/home/ops/.netrc"],
    "$HOME/.aws": ["/home/ops/.aws", "ro"],
    "$HOME/ariamh/conf/settings.conf": "/home/ops/ariamh/conf/settings.conf"
  },
  "dependency_images": [
    {
      "container_image_name": "aria/isce_giant:latest",
      "container_image_url": "$CODE_BUCKET_URL/aria-isce_giant-latest.tar.gz",
      "container_mappings": {
        "$HOME/.netrc": ["/root/.netrc"],
        "$HOME/.aws": ["/root/.aws", "ro"]
      }
    }
  ],
  "runtime_options": {
      "gpus": "all"
  },
"soft_time_limit": 900,
"time_limit": 960,
"disable_pre_builtins": false, 
"pre": [ "some.python.preprocessor.function" ], 
"disable_post_builtins": false, 
"post": [ "hysds.utils.triage" ], 
"params": [ 
{ "name": "localize_url", "destination": "localize" }, 
{ "name": "file", "destination": "positional" }, 
{ "name": "prod_name", "destination": "context" } 
] 
}

Page source: Job and HySDS IO Specifications

source ~/verdi/bin/activate

~/verdi/ops/hysds/scripts/ingest_dataset.py <product_dir> datasets.json

Page source: How to manually ingest a dataset into GRQ/S3

Wiki Content Labels

Labels are an important component of each page. They improve navigation and usability of the wiki. Every document has a combination of stateful and content-related variables.

Part 1: Open Label Window

i.) In the upper right corner, click the “…”

ii). Click “add labels”

iii.) In the pop-up window, apply the appropriate labels from Part 2 and Part 3 below:

Part 2: Select Stateful Labels

Assign exactly one label from each column (3 total from the blue table):

Content Type:	Subject Matter Expert:	Page Maintainer:

Content Type:	Subject Matter Expert:	Page Maintainer:
step_by_step_guides	needs_sme	needs_pm
reference	sme_assigned	pm_assigned
cheatsheets	update_sme	update_pm
development

Part 2: Select Content Labels

Apply any of the following labels that are applicable to your document:

Tech Labels:	HySDS Specific:	Content Variables:

Tech Labels:	HySDS Specific:	Content Variables:
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
jenkins	sdswatch
docker	pge
github	provenance
terraform	metrics
sciflo	chimera
json	tasks
api	pleiades
yaml	pcm
azure

Related Articles:
Page: Contribution Guidelines Page: Contributor Guide Page: Decision Blueprint Page: Directory Page: Document Contribution Guide Page: Document Quick Start Page: Google Season of Docs 2019 Page: Operations Manual Page: Page Feedback: Thumbs Down Page: Placeholder Articles Table Page: Project plans Page: Roadmap

Have Questions? Ask a HySDS Developer:

Anyone can join our public Slack channel to learn more about HySDS. JPL employees can join #HySDS-Community

JPLers can also ask HySDS questions at Stack Overflow Enterprise

Page Information:

Was this page useful?

Yes No

Contribution History:

Topher Allen (1537 days ago)

Subject Matter Expert:

@Marjorie Lucas

@Lan Dang

Find an Error?

Is this document outdated or inaccurate? Please contact the assigned Page Maintainer:

@Marjorie Lucas

Document Contribution Guide

Overview

Who is Your Intended Audience?

Step-by-Step Guides (Problem-Oriented)

Elements of a Step-by-Step Guide

Voice and tone

Writing principles

A Little Flexibility

Good Naming

Tips and tricks

Cheat Sheets (Information-Oriented)

Elements of a Cheat Sheet

Voice and tone

Writing principles

Structure

Consistency

Description

Accuracy

Tips and tricks

Tutorials (Learning-Oriented)

Elements of a Tutorial

Voice and tone

Writing principles

Inspire Confidence

Learning by Doing

Concrete, not abstract

Repeatability

Tips and tricks

Discussions (Understanding-Oriented)

Elements of a Tutorial

Voice and tone

Writing principles

Making Connections

Understanding Oriented

Tips and tricks

Style Guide

Voice

Tone

Audience

Clarity

Sentences

Page Elements

Screenshots

Code

Diagrams

SME

Labels

Page Maintainers

Tables

Page Element Examples

Screenshots

Tips and tricks

Code

Tips and tricks

Wiki Content Labels

Part 1: Open Label Window

Part 2: Select Stateful Labels

Part 2: Select Content Labels

Writing principles 

Tips and tricks 

Writing principles 

Tips and tricks 

Writing principles 

Tips and tricks 

Writing principles 

Tips and tricks 

Tips and tricks 

Tips and tricks 