Documentation: Intentions

It’s time to start my first big personal python project. I’ve put in the hours (and hours) in tutorials, build out a few apps, some simple some more complex, contributed to open source, and joined and contributed to a variety of python related groups. I feel about as ready as I ever will be to take the leap and get my hands dirty again in a project that’s going to extend my skills.

Part of this journey will be getting good at documentation. I’ll be using a docs as code approach.

Docs as Code#

Docs as code is the practice of applying software development techniques to writing documents.

The rules to follow are:#

I store doc source files in a version-control system.

I build the doc artifacts automatically.

I ensure that a trusted set of reviewers reviews the docs.

I publish the artifacts without much human intervention.

Added: I use a documentation CI/CD pipeline.*

Suggestions for Great Documents#

Start with What the Reader Needs#

The documentation assists the reader in achieving a goal. Understanding the needs of the reader is vital to writing good documentation.

Write Less#

Prune existing documentation. Focus on what will assist the reader achieve their goals and nothing else. The best way to avoid documentation rot it to focus it on the needs. The documentation must evolve.

Write the Outline First#

Avoid blank page writer’s block by starting with an outline. Structured documentation is easy to search, read, and maintain. Topic based writing focuses the content and helps the author write concise and less text.

Rubber Duck Test your Documentation#

Explain how the reader can achieve their goal in a friendly and conversational way. Read it out loud to check if it sounds good and reads well.

Write Readably#

The documentation has to score high for readability.

It has to be structured.
The document must have headings and sections. The headings should enable quick searching of the document and help readers identify the paragraphs of use to them.
Code must be formatted.
Do this then that instructions must be presented as lists.
Paragraphs must be short, and sentences should not be longer than 25 to 30 words.
Tell the reader what to do. Be direct.

Automating the Documentation Workflow#

A robust documentation CI/CD pipeline is required to automate and standardise, and speed up documentation workflow.

The documentation pipeline should be both robust and flexible to be reused with minimal changes to work across multiple projects.

Linters will be used to check docstring formatting for API’s. #TODO-RESEARCH

Linters will automatically check and warn spellchecking, sentence length, paragraph length, equality checking and stop word exclusion. Linters will be include in the makefile and possibly in precommit. #TODO-RESEARCH

I have used MkDocs and will investigate Sphinx as the documentation generation tool for my projects.

Documentation will be traceable.

Documentation will be linked to documentation sources.
Version control will give information about authorship and reasons behind changes.
Documentation versioning will follow Semantic Versioning 2.0.0

Style Guidelines#

Standard language conventions will be used in accordance to PEP 257.
Any project specific standards will be codified.
Docstring style will follow google style docstrings.
All chosen documentation tools will be defined and links to their documentation will be provided.

Measurability#

The generation of documentation will be in response to issues generated in GitHub.

I will explore unit testing of code examples if and when it is necessary to include code samples. For more information, see Ben Perlmutter talk Unit test the Docs: Why You Should Test Your Code Examples (Write the Docs Portland 2022) The talk references a markup processor for extracting code and making it into examples. #TODO-RESEARCH