Skip to Main Content
It looks like you're using Internet Explorer 11 or older. This website works best with modern browsers such as the latest versions of Chrome, Firefox, Safari, and Edge. If you continue with this browser, you may see unexpected results.
Image Source: https://stfalcon.com/uploads/images/55c8bcff18b94.png.
Why to Write Documentation
Documentation effectively connects humans and machines.
Why writing documentation:
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
Others can easily use your code and build upon it
Advance the science
Encourage open science
Allow reproducibility and transparency
Best Practices for Documenting Your Project
An example for README file.
Best practices for writing documentation:
Include A README file that contains
A brief description of the project
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
An example for code documentation.
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
An important tip: Naming files should be descriptive and consistent!
Tools for Documentation
Tools for documentation:
Software documentation hosting options:
Research Data Management Program Service Lead