Doc guidelines, standards, and tools

Practical guidelines for creating good docs and help with related tools.

  2 minute read  

Here are some tools, resources, and guidelines for creating docs.

Notes

Doc project tenets

Guiding principles for doc projects…unless you can think of better ones.

GROW Content Process

Develop content in an agile fashion (and handle writer’s block)

Readability scores

Shows how readability scores (and modern writing principles) lead to better docs.

Style guides

Defines “style guide” as a term and offers recommendations.

Voice & tone principles

Principles for clear, readable docs.

Hugo

Tips and tricks for Hugo, a static site generator.

Markdown

Markdown is a text-based markup language used for docs and other publications.

MKDocs

Tips and tricks for MKDocs, a static site generator.

Pandoc conversion tips

Helpful tips for using pandoc to convert documents to Markdown

Vale: a prose linter

A command-line tool that validates content against a set of known rules. Think of it as your personal style checker.

Markup viewers

Many tools leverage common markup formats, such as Markdown and Restructured Text (RST). The following editors can help you learn these formats using local previews:

  • Markdown-Viewer is one of several Markdown viewers available on GitHub. This supports LaTeX math equations and Mermaid diagrams. It also calculated readability statistics.

  • LiveSphinx supports Restructured Text and Sphinx extensions.

  • Both Visual Studio Code and IntelliJ feature

Each tool can be incorporated into a content pipeline as part of a docs-as-code process.

As of this writing, each of these tool operate locally, which means your content is not sent to another server or used to train an AI model. This depends, in part, on your local environment, such as your browser or how the tool is hosted.

Diagram & drawing tools

  • Draw.io (also known as diagrams.net) can make visually pleasing diagrams with minimal effort.

    Some tips:

    • If your diagram contains an element with wrapped text, design that element first and then use it as the starting point for the rest of your elements.

    • Strongly recommend using a mouse, trackball, or precision pointing device. Alignment is difficult when using gestures or other touch interface controls.

    • Set a background color in document properties; otherwise, your final diagram might be transparent.

    • If saving is problematic, save to your local device and then move the file to your intended destination.

  • asciiflow creates simple line drawing diagrams using ASCII line drawing characters. Helpful for text file illustrations.

  • Pencil project is a cross-platform Visio alternative.