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://github.com/ybouz2/project-tech/wiki/Coding-standarts
Why to Write Documentation
Documentation effectively connects humans and machines.
Why writing documentation is important:
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
What should you document about your research? Everything! All the data, notes, code, and materials someone else would need to reproduce your work.
Consider the following questions:
How is your data gathered?
What variables did you use?
Did you use any code to clean/analyze your data?
Best Practices for Documenting Your Project
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 does
What are 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 versions of the files along with the major edits you did in each version
An important tip: Naming files should be descriptive and consistent!
Date format (ISO 8601 Standard): YYYYMMDDThhmmss
Make file names sortable and searchable:
Project or experiment name
Date or date range of collection version
An example for README file.
An example of code documentation.
Tools for Documentation
Tools for Documentation:
Software Documentation Hosting Options: