Documentation can take many forms and can be hot button issue.
Types
My favorite take on this subject has been Daniele Procida’s talk at PyCon Australia 2017. He argues that there are four types: Tutorials, How-To Guides, Discussions, and Reference.
- Tutorials: Lessons that take the reader by the hand through a series of steps to complete a project.
- How-To Guides: Guides that take the reader through the steps required to solve a common problem.
- Discussions: Explanations that clarify and illuminate a particular topic.
- Reference: Technical descriptions of the machinery and how to operate it.