Skip to main content

How to Write a Good Documentation: Home

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

Documentation

Image Source: https://stfalcon.com/uploads/images/55c8bcff18b94.png.

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:

Copyright © 2014-2019 The Regents of the University of California. All rights reserved. Except where otherwise noted, this work is subject to a Creative Commons Attribution-Noncommercial 4.0 License.