Doc guidelines, standards, and tools

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

  less than a minute  

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.

Diagrams

  • 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.