3.5. Documentations

What are software documentations?

Software documentation encompasses written text or illustrations that support a software project. It can range from comprehensive API documentation to high-level overviews, guides, and tutorials. Effective documentation plays a crucial role in assisting users and contributors by explaining how to utilize and contribute to a project, ensuring the software is accessible and maintainable.

Why do you need to create documentations?

Documentation is pivotal for several reasons:

• Usability: It aids users in understanding how to interact with your software, detailing accepted inputs and expected outputs.
• Maintainability: Documentation facilitates new contributors in navigating the codebase and contributing efficiently, such as guiding through the process of submitting a pull request.
• Longevity: Projects with thorough documentation are more likely to be adopted, maintained, and enhanced over time, thanks to resources like troubleshooting sections.
• Quality Assurance: The process of writing documentation can uncover design issues or bugs, much like explaining a problem aloud can lead to solutions (e.g., through a data glossary).

High-quality documentation encourages the use of your software and is valued by your users, while poor documentation can hinder developer productivity and deter users from engaging with your solution.

How should you associate documentations to your code base?

Documentation within Python code can be incorporated in three key places:

• Module documentation: This should be placed at the top of your Python module to provide an overview.

"""Define trainable machine learning models."""

• Function or method documentation: Use this to describe the purpose of functions or methods, their parameters, and return values.

def parse_file(path: str) -> Config:
    """Parse a config file from a given path.

    Args:
        path (str): Path to the local config file.

    Returns:
        Config: Parsed representation of the config file.
    """
    return oc.OmegaConf.load(path)

• Class documentation: Here, you describe the purpose and parameters of a class.

class ParquetReader(Reader):
    """Reads a dataframe from a parquet file.

    Attributes:
        path (str): The local path to the dataset.
    """

    path: str

Beyond in-code documentation, complementing it with external documentation (e.g., project organization guides or how to report a bug) is beneficial.

Which tool, format, and convention should you use to create documentations?

For creating documentation, you have multiple tools, formats, and conventions at your disposal:

• Tools:

  • MkDocs: A fast, simple static site generator designed for project documentation, built with Python.
  • pdoc: A tool and library for auto-generating API documentation for Python projects, best for API docs.
  • Sphinx: A robust tool for creating detailed and beautiful documentation, popular within the Python community, albeit with a steeper setup curve.

• Formats:

  • Markdown: A straightforward text format that converts to HTML, ideal for simpler docs.
  • reStructuredText (reST): Offers more features than Markdown, widely used in Python documentation, especially with Sphinx.

• Convention:

  • Numpy Style: Features a clear, structured format for documenting Python functions, classes, and modules, focusing on readability.
  • Google Style: Known for its simplicity and ease of use in documenting Python code, emphasizing clarity and brevity.
  • reStructuredText: Offers a comprehensive set of markup syntax and constructs, ideal for technical documentation that requires detailed structuring and cross-referencing.

For best practices, choose a tool and format that align with your project's needs and complexity. Adopting a widely recognized convention can facilitate consistency and comprehension across your documentation. Generating a simple API documentation can be as simple as calling a tool like pdoc with an input and output directory:

$ poetry run pdoc --docformat=google --output-directory=docs/ src/bikes

You can also use your IDE or some extensions like autoDocstring to automate the documentation generation process.

Is there some frameworks for organizing good documentation?

Diataxis is a framework that offers a systematic approach to crafting technical documentation, recognizing four distinct documentation needs: tutorials, how-to guides, technical references, and explanations. It suggests organizing documentation to align with these needs, ensuring users find the information they're looking for efficiently.

What are best practices for writing your project documentation?

1. Clarity and Conciseness: Strive for clear, straightforward documentation, avoiding complex language or unnecessary technical jargon.
2. Consistent Style: Maintain a uniform style and format throughout all documentation to enhance readability.
3. Keep It Updated: Regularly revise documentation to reflect the latest changes and additions to your software.
4. Use Examples: Provide practical examples to illustrate how different parts of your software operate.
5. Accessibility: Ensure your documentation is accessible to all users, including those with disabilities.
6. Feedback Loop: Encourage and incorporate feedback on your documentation to continuously improve its quality.
7. Multilingual Support: If possible, offer documentation in multiple languages to cater to a wider audience.
8. Searchable: Implement search functionality to allow users to quickly locate relevant information within your documentation.
9. Versioning: If your software has multiple versions, provide corresponding documentation for each version.

Documentation additional resources

• Documentation example from the MLOps Python Package
• Diátaxis: A systematic approach to technical documentation authoring