Your tasks: Software documentation

How to craft effective software documentation?

Software documentation is an essential part of the software development process, designed to provide clear communication between various stakeholders including developers, testers, users, and project managers. It helps align the expectations and goals of all parties, while also ensuring the software is easy to understand and use.

Considerations

• Software documentation should be clear, consistent, regularly updated, cover all key aspects, encourage feedback, and ideally be auto-generated.
• Each document should have a distinct purpose.
• There are two types of software documentation:
  • Product documentation targets both internal and external users (e.g., Requirements Documents, often in ReadMe files; Source Code Documentation, which includes code; End-User Documentation, like user guides and API references for usability).
  • Process documentation is primarily intended for the development team (e.g., Plans; Progress Reports track progress; Working Papers capture ideas and notes from the team).

Solutions

Understand the Purpose and Audience

• Define why the document is being created and who will be using it.
• Understanding the purpose allows you to tailor the content accordingly.
• For example:
  • A developer-facing document will need in-depth technical details.
  • An end-user guide should focus on usability and clarity, offering step-by-step instructions.
• Create personas to represent your audience for better-targeted technical content, it helps categorize your help documentation.

Write Comments as You Code

• Use integrated development environments (IDEs) that automatically generate documentation strings, such as Eclipse,Pycharm for Python and Visual Studio Code using extensions like JSDoc or Python Docstring Generator.
• Ensure you strike a balance in the amount of commenting.

Include Examples (and Lots of Them)

• Examples help users understand and experiment with the software.
• Unlike with comments, there’s no such thing as too many examples if they showcase different aspects of your software.
• If your documentation becomes too cluttered, consider moving examples to a dedicated section.
• For instance, Keras provides example scripts to demonstrate its functionalities along with a README file that outlines.

Include a Quickstart Guide

• A quickstart guide enables users to move quickly from idea to experimentation.
• This can take the form of an example, tutorial, or video.
• For instance, the quickstart guide for TPOT includes an animated GIF and minimal code snippets.

Include a README File with Basic Information

• The README acts as a homepage for your project and should be easily readable.
• It include a link to the full documentation.
• [See more details about the README file](link to “how create a good readme?” page)

Include a Help Command for Command Line Interfaces

• An effective way to document CLIs is to implement a help command that provides instructions on how to use the software.
• This approach ensures that users don’t have to search for documentation to complete basic tasks.
• The help command should cover
  • Usage instructions (how to execute the command).
  • Relevant subcommands
  • Options and/or arguments
  • Applicable environment variables
  • And ideally, some examples.

• In Python, tools like Click can assist you not only in creating your help command but also in building your interface.

• A great example of a CLI is the one included in Magic-BLAST. It features a concise help command, -h which offers :
  • Information about the tool and its usage.
  • Instructions for accessing the help documentation.

Version Control Your Documentation

• Since your documentation is a crucial component of your code, it should also be under version control.
• Store your documentation within your Git repository alongside your other files. This approach allows you to access your documentation at any stage of the project’s history.
• Services like Read the Docs and Zenodo facilitate this process by archiving a fully rendered version of your documentation each time you release a new version of your software.

• Here are details about how to create a readthedocs page.

• A noteworthy example of a bioinformatics library effectively managing version control for its documentation is khmer. This library features a comprehensive changelog that details new features, bug fixes (categorized based on relevance to users or developers), known issues, and a list of contributors for each release .

Fully Document Your Application Programming Interface (API)

• Your API documentation should be complete and accessible, serving as a reference for users.

• Maintaining a consistent style in your API documentation is crucial.

• The Google style guide offers recommendations for API documentation across various programming languages, including Python, Java, R, C++, and Shell.

Use Automated Documentation Tools

• While no software can completely handle your documentation needs, several tools can significantly ease the process:

• Tools like Sphinx and Doxygen can generate documentation in multiple formats (HTML, PDF) and automatically extract comments from your codebase.

• MkDocs enable the creation of professional-looking documentation websites using Markdown, making navigation easy for users.

• Tools such as Swagger automatically generate interactive API documentation, providing user-friendly interfaces for developers.

• Roxygen and JSDoc simplify the process of generating documentation from annotated code in R and JavaScript, respectively.

• Please find a more comprehensive list of the documentation tools provided below.

Write Error Messages That Provide Solutions or Point to Your Documentation

• Error messages should clearly state :
  • What went wrong
  • The state of the software
  • When the error occurred
  • How to fix it or where to find relevant information.
• For example, instead of a vague error message, provide specifics that help users troubleshoot.

Tell People How to Cite Your Software

• Ensure that your documentation includes clear instructions on how to cite your work.
• See [How to cite your code repository and maintain a Citation File (CFF)].

How to cite this page

contributors, page URL. Last date of access.

Tools and resources

List of relevant tools and resources for this task. | Tool or resource | Description | | ——————- | ———— | |Sphinx | A documentation generator primarily designed for Python but compatible with any programming language. It reads comments in the code to create detailed API documentation. | |Roxygen | A documentation generator specifically designed for R packages. | | MkDocs | A documentation generator from Markdown files. | | Doxygen | A documentation generator from annotated source code in multiple programming languages. | | Read the Docs | A platform that automatically rebuilds documentation with each code update. | | Doctest | A Sphinx extension that verifies code examples in documentation to ensure they work as described. | | Napoleon| A Sphinx extension that enables support for Google and NumPy style docstrings to generate API documentation. | |Swagger|A tool for generating interactive documentation for RESTful APIs. | |Click|A library for creating user-friendly command-line interfaces (CLIs), enabling structured commands and automatic help generation. | |Zenodo|Zenodo supports version control for documentation by archiving and storing different versions of project’s documentation.| |khmer|A library that offers a comprehensive changelog detailing features, bug fixes, known issues, and contributors, along with accessible documentation for previous versions. | |Google style guide|The Google style guide offers comprehensive recommendations for maintaining consistency in API documentation across multiple programming languages, such as Python, Java, R, C++, and Shell.| |Eclipse | IDE offering features to generate Javadoc comments for Java classes and methods based on their signatures. | PyCharm | A powerful IDE for Python development, featuring intelligent code assistance and built-in documentation generation. | | Visual Studio Code | A popular code editor that supports various languages and allows the use of extensions for documentation generation. | | JSDoc | An extension to generate documentation from comments in JavaScript code. | | Python Docstring Generator | An extension for Visual Studio Code that automatically generates docstrings for Python functions and classes. |

Credit

The contents of this page have been inspired by

• Ten Simple Rules for documenting scientific software. [1]
• Best Practices for Scientific Computing. [2]
• Ten Simple Rules for Taking Advantage of Git and GitHub. [3]
• How to Write Software Documentation in 7 Simple Steps

References

1. Lee B. D., Ten Simple Rules for documenting scientific software
2. Wilson, G., Aruliah, D. A., Brown, C. T., Chue Hong, N. P., Davis, M., Guy, R. T., Haddock, S. H., Huff, K. D., Mitchell, I. M., Plumbley, M. D., Waugh, B., White, E. P., & Wilson, P.Best Practices for Scientific Computing
3. Perez-Riverol Y, Gatto L, Wang R, Sachsenberg T, Uszkoreit J, Leprevost FdV, et al. Ten Simple Rules for Taking Advantage of Git and GitHub

Related pages

Tools and resources on this page

Skip national tools table

National resources

Tools and resources tailored to users in different countries.

Contributors