Discussion : Documentation Tools

[zaya-mc]

We need documentation tools for below;

The requirements for documentation could be;

1. Low external dependency as much as possible (Handle in the github project if you can)
2. Easy to version for modifications.

These are my suggestions;

• Coding Documentation

  1. Self-Commented Code; The code implementation needs to be clears and easy to read. Herein, we
     need Coding Convention Standards. Coding convention will be handled in a different ticket.
  2. Doxygen Style Code Comments: File comment style (File, Function Headers etc) in Doxygen style to get API documentation from the code. (In the product releases, we can run doxygen to get API documentation easily. )

• Tutorials; I would prefer using the Github Wiki pages for tutorials (Life Cycle Rules, Git Rules etc), in this way we can handle coding and documentation in the single tool (Github).
  And once a developer forks (git fork), the fork will get the Wiki documentation from the original repo.
  Github Wiki's offers also hierarchical documentation.

• Internal Documentation in the code repository; we can use MD file which is widely used in open source projects for documentation. (Example from this repo : https://github.com/OpenIoTAcademy/EmbeddedTemplate/blob/master/README.md )The browsers recognise MD files and its format (bold, italic etc).
  The other advantage is that it is in plaintext format so we can trace the difference using version control tools (git) which is challenging for MS WORD or PDF.