Documentation

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

Sections

• Contributions README
• Design Document
• UMLDiagrams

Related Sections

• 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

Markdown is commenly used for documentation.

• Markdown

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 static websites)
• 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 text files (or Markdown files stored in a repository)

Writing Documentation Guides

• WriteTheDocs: beginners-guide-to-docs

Example Documentations

• GitHub MicrosoftDocs/azure-docs

Additional Resources

TODO: Research more about GitHub Wikis

https://guides.github.com/features/wikis/

https://guides.github.com/

https://docs.github.com/en/free-pro-team@latest/github/building-a-strong-community/about-wikis

https://docs.github.com/en/free-pro-team@latest/github/building-a-strong-community/adding-or-editing-wiki-pages

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

Other

• UMLDiagrams

Journal

• 2020.06.26 Created file
• 2020.07.29
  • Added sections for specific documentation frameworks
  • Added Advertising information
• 2020-11-16
  • Added Additional Resources section
• 2020-12-26
  • added Example Documentations section
• 2020-12-29 Added UML Diagram section
• 2021-01-22 Added note about purpose of code being understanderstandable and commenting being documentation
• 2021-03-10 Added links to related sections
• 2021-04-09
  • Created Markdown section
  • Created Forms of Documentation section
  • Added additional beliefs on documentation
  • Added link to Writing Code that Lasts page