Documentation Conventions

Original article published at Project Standards repo on my GitHub account (polatengin), you can find it on Documentation Conventions page.

Especially big and complex projects, documentation is crucial.

There are good phrases in Zen of Python;

Explicit is better than implicit

Readability counts

Documentation should be descriptive, easy to understand, applicable and should not produce more question marks than it solved.

Since good documentation is important, there should be some guideline or check-list to make sure that the documentation is good ??

Here is an opinionated check-list for good documentation;

• Documentation should be in a universal format, such as, Markdown, Microsoft Word, Microsoft Powerpoint, etc.
• If it's possible, documentation should be in Markdown format.
• If it's possible, use Visual Studio Code to create documentation.
• Use Markdown Lint extension on Visual Studio Code to check Markdown errors before saving the document.
• If you're using Markdown, always use Markdown syntax, don't mix it with HTML or other syntaxes.
• Always start with the biggest heading (single # in Markdown).
• Use smaller headings after the Main Headline (biggest heading).
• Use headings to create a Table of Contents.
• Use Markdown TOC extension time-to-time to check if the headings are in correct size or not.
• Always add a description right after headings, don't continue with a list or another heading.
• Use emphasis' to draw attention on part of the sentence and make it more visible.
• If it's possible, use screenshots or animated screenshots (a.k.a gif) to explain the section visually.
• If you share a code part, always put it between triple-ticks (```)
• After the first triple-ticks, put the language of the code you're sharing, for example, ```bash.
• Don't use here to create an external reference, use the name of the external reference document, for example, instead of (You can see the reference in here) , use (You can see the reference in Project Standards).
• Always follow chronological order to create good documentation. Don't jump between later and prior in time.
• Always read your own documentation before publish it, if it's possible, ask someone else to read it for you and make suggestions to you.
• Always add a References section at the end.