Documentation Style Guide

Thank you for taking an interest in contributing to Pachyderm’s docs! 🐘 📖

This style guide provides editorial guidelines for writing clear and consistent Pachyderm product documentation. See our contribution guide for instructions on how to draft and submit changes.

Audience #

Pachyderm has two main audiences:

• MLOPs Engineers: They install and configure Pachyderm to transform data using pipelines.
• Data Scientists & Data/ML Engineers: They plan the development of pipelines and consume the outputs of Pachyderm’s data processing to feed AI/ML models.

Be sure to provide links to pre-requisite or contextual materials whenever possible, as everyone’s experience level and career journey is different.

Voice & Tone #

Pachyderm’s voice in documentation should consistently convey a personality that is friendly, knowledgeable, and empathetic.

The tone of voice may vary depending on the type of content being written. For example, a danger notice may use an urgent and serious tone while a tutorial may use an energetic and instructive tone. Make sure the tone of your documentation aligns with the content. If you aren’t sure what tone to convey, ask yourself: “What is the reader likely feeling when presented this content? Why are they here?” and adjust your language to the most appropriate tone.

Language & Grammar #

The following guidelines are to be followed loosely; use your best judgment when approaching content – there are always exceptions.

Use Active Voice #

Write in active voice to enforce clarity and simplicity.

You can break this rule to emphasize an object (the image is installed) or de-emphasize a subject (5 errors were found in this article).

Use Global English #

Write documentation using Global English. Global English makes comprehension easier for all audiences by avoiding regional idioms/expressions and standardizing spelling words using the US English variant.

Put Conditional Clauses First #

Order conditional clauses first when drafting sentences; this empowers the reader to skip to the next step when the condition does not apply.

Write Accessibly #

Be mindful of how you describe software behavior and users; in particular, avoid ableist language. Use generic “they/them” and “you” when describing users or actors; avoid the use of “obviously”, “simply”, “easily” – every reader has a different level of expertise and familiarity with key concepts/tools.

Formatting & Punctuation #

Markdown #

All documentation is written using Markdown syntax in .md files. See this official Markdown Cheat Sheet for a quick introduction to the syntax.

Code Blocks #

Use ``` to wrap long code samples into a code block.

This is a code block.

Headers #

Use title casing for all header titles.

• Capitalize the first and last word.
• Capitalize adjectives, adverbs, nouns, pronouns, and subordinate conjuctions.
• Lowercase articles (a, an, the) and coordinating conjunctions (and, but,for, nor, or, so, yet).

Links #

Use meaningful link descriptions, such as the original article’s title or a one-line summarization of its contents.

Examples:

- See the [Pachyderm Technical Documentation Style Guide](../docs-style-guide)
- Use the [official Pachyderm style guide](../docs-style-guide).

Lists #

• Use numbered lists for sequential items, such as instructions.
• Use unbulleted lists for all other list types (like this list).

Commas #

Use the serial or Oxford comma in a list of three or more items to minimize any chance of confusion.

UI Elements #

Bold UI elements when mentioned in a set of instructions (a numbered list).

1. Navigate to Settings > Desktop.
2. Scroll to Push Notifications.

Organization #

Use Nested Headers #

Remember to use all header sizes (h1-h6) to organize information. Each header should be a subset of topics or examples more narrow in scope than its parents. This enables readers to both gain more context and mentally parse the information at a glance.

Publish Modular Topics #

Avoid mixing objectives or use cases in one article; instead, organize and separate your content so that it is task-based. If there are many substasks (such as in a long-form tutorial), organize your content so that each major step is itself an article.

Examples:

The below outlines are 4 articles, with the parent article linking to each modular sub-topic.

• How to Locally Deploy Pachyderm
  • MacOS Local Deployment Guide
  • Linux Local Deployment Guide
  • Windows Local Deployment Guide

Images & Diagrams #

Visualizations are helpful in learning complex workflows and UIs; however, they can expire quickly and take a lot of effort to maintain. Ask yourself the following questions when deciding whether or not to add visualizations:

• Is the user interface complex enough to warrant a screenshot?
• Can a diagram convey this concept more efficiently than words?
• How frequently does this visual need to be updated?

Also, remember to add alt-text to your visualizations for screen readers.

Mermaid #

You can build diagrams using mermaid.js in our documentation by:

1. Adding mermaid: true to the frontmatter of an article.
2. Drafting a diagram, like so:

    ```mermaid
    graph TD;
        A-->B;
        A-->C;
        B-->D;
        C-->D;
    ```

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
  

Want to make an update to this style guide? Select Edit on Github and leave a suggestion as a pull request!