Skip to content

Latest commit

 

History

History
52 lines (27 loc) · 2.68 KB

Documentation-Conventions.md

File metadata and controls

52 lines (27 loc) · 2.68 KB

Documentation Conventions

Documentation Conventions

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