Documenting Software Code
2017, Sep 11
How to Write a Good Documentation
Why to Write Documentation
Documentation effectively connects humans and machines.
Why writing documentation:
- For you
- You will be using your code in 6 months
- You want people to use your code and give you credit
- You want to learn self-determination
- Others would be encouraged to contribute to your code
- For others: Others can easily use your code and build upon it
- For science:
- Advance the science
- Encourage open science
- Allow reproducibility and transparency
Best Practices for Documenting Your Project
Best practices for writing documentation:
* Include A README file that contains
* A brief description of the project
* Installation instructions
* A short example/tutorial
* Allow issue tracker for others
* Write an API documentation
* What a function do
* What the function's parameters or arguments are
* What a function returns
* Document your code
* Apply coding conventions, such as file organization, comments, naming conventions, programming practices, etc.
* Include information for contributors
* Include citation information
* Include licensing information
* Link to your e-mail address at the end
* List all the version of the files along with the major edits you did in each version