Skip to Main Content

How to Write Good Documentation: Home

This guide will help you to prepare your code for publishing through writing a good documentation.

Documentation

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:

  • 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

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:

  1. Include a README file that contains
    • A brief description of the project
    • Installation instructions
    • A short example/tutorial
  2. Allow issue tracker for others
  3. Write an API documentation
    • What a function does
    • What are the function's parameters or arguments are
    • What a function returns
     
     
  4. Document your code
  5. Apply coding conventions, such as file organization, comments, naming conventions, programming practices, etc.
  6. Include information for contributors
  7. Include citation information
  8. Include licensing information
  9. Link to your e-mail address at the end
  10. 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
    • Researcher name/initials
    • 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: