Documentation
Documentation
Created by Moorthy and @mskmoorthy
Importance
- Ease of Maintenance
- Ease of Use of Code
- Encourage Entry Level People
- Importatnt mode of communicating with others
- Code may vanish - documentation remain
Different Types of Documentation
- wiki
- blog
- user manual
- program documentation
- Readme files
In Class Exercise
- Create a repository Doc-ex1 in your github page
- In the side bar menu, createa wiki page
- Add content to the wiki page using mark down
- Add another wiki page add content in restructured tex
- Example (mark down) first page in markdown
- Example (restructured text) restructured example
What we learned so far
- markdown
- restructured text
- Assuming you already know about some mark up language such as html (html5), css - If you do not know css go through this tutorial W3 School Go through first Five lessons.
- Other markup languages are xml - similar to html.
CSS Off/On Class exercise
- sinorcaish css and edit this document and modify Sample
LaTeX
- Commonly used markup language for scientific communications.
- Collaborative and online tool (WYSWYG)
- another WYSWYG editor with different output
- Try typing $e^{i \pi} =-1 $ and see what renders as an image
- Please read Latex basics ; Overleaf (supports git repo) and In class exercise modify the Paper to change the title, author and the introduction.
Literate Programming
- Produce a document which contains both code and documentation coexist. Literate programming
- Knuth has written books based on his TeX, Metafont software (with interspersed code
- Dynamic Report Generation in R
- ipython notebook is another example for python
- Read this blog about Ipython Literate Programming
Two Sample Programs
Community Participation
- quora
- stackoverflow
- online mailing list