“Software documentation is written text or illustration that accompanies computer software or is embedded in the source code.”
Reference: wikipedia: Software documentation
Documentation plays a key role in Writing Code That Lasts
There is little good in building something if nobody knows how to use it.
- Documentation shuld be standalone pieaces. It should have enough information for someone to be able to follow without additional assistance.
- When creating documentation, someone unfamiliar with the service should be able to understand or follow what was written.
- Don’t be ambigious. Add information that others may not know.
- I believe that documenation should be timeless. If years have passed and you forget everything, you should be able to relearn from scratch about a project via the written documentation.
- Documentation should be accessible.
- If people cannot find the information, then it is not useful documentation.
- This could mean taking time when appropriate to organize the information so that people can find and be aware of the documentaion.
- Contribnutions README.md: Used to establish a procedure of how to contribute to a project.
- Design Document: Used for planning how to implement a feature.
- UML Diagrams: The Unified Modeling Language is used to visualize the design of a system
Markdown is commenly used for documentation.
Forms of Documentation
- Comments in source code is a form of documentation.
Comment explanations & links to websites that you referenced that will assist others in understanding what's occurring.This will help others understand the project so they won’t be overwhelmed and speed up how long it takes to onboard someone onto the project.
- Adding links to source code as comments can be very useful.
- Typically, then source code is compiled, comments are removed from the deployed program automatically. (Note: This may not be the case for
- Documentation could be notes on the service stored in a seperate repository, a hosted website, a local folder, or a folder in the current proeject.
- Docuemntation can be
Markdown filesstored in a repository)
Writing Documentation Guides
TODO: Research more about GitHub Wikis
Flutter documentation: https://github.com/flutter/website
MkDocs: for Simplicity
Getting Started with MkDocs
Material Design for MkDocs Documentation
Sphinx: for POWER
Getting Started with Sphinx
Material Design for Sphinx Documentation
Hosting with Read the Docs
Read the Docs: Read the Docs simplifies software documentation by automating building, versioning, and hosting of your docs for you.
- Interesting: Read the Docs Revenue Model: Ethical Advertising
Advertising on documentation Topic
This is interesting: Using Ads to Sustain Open Source
- 2020.06.26 Created file
- Added sections for specific documentation frameworks
- Added Advertising information
- Added Additional Resources section
- 2020-12-29 Added
- 2021-01-22 Added note about purpose of code being understanderstandable and commenting being documentation
- 2021-03-10 Added links to related sections
Forms of Documentationsection
- Added additional beliefs on documentation
- Added link to
Writing Code that Lastspage