Pachyderm Technical Documentation Style Guide

This document provides main guidelines for creating technical content that describes Pachyderm concepts and operations. This style guide is based on Google Developer Documentation Style Guide and serves as a quick reference for everyone who wants to contribute to the Pachyderm documentation. For a more detailed overview, see the Google Developer Documentation Style Guide.

Overview

We welcome all contributions to the Pachyderm technical documentation and are happy to help incorporate your content into our docs! We hope that this document will assits in answering some of your questions about our contributing guidelines.

Writing Style

Friendly but not overly colloquial. Avoid jargon, idioms, and references to pop culture. Use shorter sentences and words over longer alternatives.

Things to avoid:

  • "Please" and "thank you".
  • Exclamation marks.
  • Announcement of features that have not yet been developed.
  • All caps to emphasize the importance.
  • Parenthesis as much as possible. Use commas instead.
Do not use Use
We'll walk you through the installation of the product X. It might be a bit difficult, but don't worry, we are here to help. This guide walks you through the process of installation of the product X.

Write in the present tense and in second person

Say "you" instead of "we" and use the present tense where possible. Only use the future tense when talking about the events that will not happen immediately but sometime in the future. The future tense introduces uncertainty about when an action takes places. Therefore, in most cases, use the present tense.

Do not use Use
We are going to create a new configuration file that will describe our deployment. To create a new configuration file that describes our deployment, complete the following steps.

Write for an international audience

Avoid idioms and jargon and write in simple American English. The content that you are writing might later be translated into other foreign languages. Translating simple short phrases is much easier than long sentences. Use consistent terminology and avoid misplacing modifiers. Spell out abbreviations on the first occurrence.

Do not use Use
After completing these steps, you are off to the races! After you complete these steps, you can start using Pachyderm.

Write in Active Voice

Sentences written in active voice are easier for the reader to understand. A well-written text has about 95% of sentences written in active voice. Use passive voice only when the performer of the action is unknown or to avoid blaming the user for an error.

Do not use Use
This behavior means that transform.err_cmd can be used to ignore failed datums. You can use transform.err_cmd to ignore failed datums.

Put the Condition Before the Steps

If your sentence has a condition, start the sentence with the conditional clause and add the descriptive instructions after the clause.

Do not use Use
See the Spark documentation for more information. For more information, see the Spark documentation.

Use Numbered Lists for a Sequence of Steps

If the user needs to follow a set of instructions, organize them in a numbered list rather than in a bulleted list. Options can be described in a bulleted list. An exception to this rule is when you have just one step.

Do not use Use
* Create a configuration and run the following command. 1. Create a configuration file.
2. Run the following command:

Break Your Content Into Smaller Chunks

Users do not read the whole body of the text. Instead, they skip and scan through looking for the text structures that stand out, such as headings, numbered and bulleted lists, tables, and so on. Try to structure your content so that it is easy to scan through by adding more titles, organizing instructions in sequences of steps, and adding tables and lists for properties and descriptions.

Avoid Ending a Sentence with a Preposition

Phrasal verbs are a little bit less formal than single-word verbs. If possible, replace a phrasal word with a single-word verb equivalent and if you have to use a phrasal word, avoid finishing the sentence with a preposition.

Do not use Use
The put file API includes an option for splitting up the file into separate datums automatically. The put file API includes an option for splitting the file into separate datums automatically.

Link text should mean something to the users when they read it. Phrases like Click here and Read more do not provide useful information. They might be good for call-to-action (CA) buttons on the marketing part of the website, but in technical content they introduce uncertainty and confusion.

Furthermore, if a user generates a list of links or uses a speech recognition technology to navigate through the page, they use keywords and phrases, such as "Click ". Generic links are not helpful for them.

Also, use a standard phrase For more information, see to introduce a link.

Do not use Use
More information about getting your FREE trial token and activating the dashboard can be found here. For more information, see Activate your token by using the dashboard.

Markdown

The Pachyderm documentation uses Python Markdown, and many PyMdown Extensions are supported. See the mkdocs.yaml file for the list of supported extensions.

In general, follow these guidelines:

  • Do not use the admonitions in numbered lists because they break the order and Markdown does not support starting lists from an arbitrary number.
  • Enclose code blocks in "```" and specify the correct highlighting.
  • While PyMdown Extensions provide advanced UI features, use them sparingly because not all browsers fully support all of them.

I hope you'll have fun with Python Markdown! 😄