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.

Update: Moffitt Library is closed for seismic work, but most other libraries are open. Learn more.

How to Write a Good Documentation: Home

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


Image Source:

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

An example for README file
An example for README file.

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 do
    • What the function's parameters or arguments are
    • What a function returns
    An example for code documentation.
    An example for code documentation.
  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 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