MidasDocs/PoliciesAndStandards/DocumentationStandards.md

Documentation Standards

Table of Contents

1. Overview
2. Global Documentation Structure
3. Module-Specific Documentation
4. Documentation Format and Naming Conventions
5. File Requirements for Python Modules
6. Code Documentation Practices

---

Overview

This document defines the standards for documenting business, technical, and code-related affairs within the repository. It ensures that all contributors understand how and where to document essential aspects of the project, including code structure, usage, and business elements.

Footnote: While the overarching program is under active development, documentation must be updated with each pull request or addition to maintain consistency and clarity as the project grows.

---

Global Documentation Structure

All global documentation is stored under the /docs directory and is organized into the following key areas:

1. Business Documentation:

   • Contains non-technical documents that relate to company operations, legal compliance, project plans, business strategies, and any necessary licenses or contracts.
   • Directory: /docs/business
   • Examples: Business plans, contracts, project outlines, licenses.

2. Policies and Standards:

   • Contains files outlining the coding, review, and workflow standards.
   • Directory: /docs/policies-and-standards
   • Examples: GitAndGitHubStandards.md, BranchNamingConventions.md, CodingStandards.md.

3. Man Pages:

   • Stores all program-related documentation for the entire codebase.
   • Directory: /docs/manpages
   • Examples: README files detailing how to use, deploy, and modify the overarching program.

Each sub-directory should contain a README.md that outlines its purpose and lists the contents within.

---

Module-Specific Documentation

All root modules within the overarching program should contain their own README.md files. These files should act as module-specific documentation, providing:

1. Overview:

   • A brief explanation of the module’s functionality and its purpose in the larger program.

2. Installation and Setup:

   • Instructions for setting up the module, including any dependencies not covered in the global requirements file.

3. Usage:

   • How to run and utilize the module, including examples of inputs, expected outputs, and special configurations.

4. Development Guidelines:

   • If applicable, detail any specific guidelines for contributing to the module, such as coding standards, testing guidelines, or branch usage specific to the module.

5. Version and Dependencies:

   • Each module should have its own requirements.txt file that lists the dependencies required for it to function. This file will be merged into the main program’s requirements.txt by the admins.

---

Documentation Format and Naming Conventions

Format

• Markdown (.md) or Plain Text (.txt) formats are acceptable for all documentation.
• The language should be formal yet accessible, avoiding technical jargon where possible to ensure clarity for all team members and future collaborators.

Naming Conventions

• Documentation files must be in Capitalized Case with no spaces, using only letters and alphanumeric characters.
  • Examples: DocumentationStandards.md, GitAndGitHubStandards.md
• Code files should follow lowercase with underscores for Python, with no spaces or special characters.
  • Examples: data_processing.py, config_handler.py

---

File Requirements for Python Modules

Main requirements.txt

A main requirements.txt file will exist in the root directory of the program. This file aggregates all module-specific dependencies to provide a comprehensive list of requirements for the entire program.

Module-Specific requirements.txt

• Each root module in Python must include its own requirements.txt file, specifying only the dependencies necessary for that module.
• Upon review, the admins will incorporate module-specific requirements into the main requirements.txt.

---

Code Documentation Practices

General Code Documentation Guidelines

Documentation within code should provide clarity and context without redundancy. Focus on documenting the why and how rather than the what.

• Functions and Methods:

  • Include docstrings for all public functions and methods. These should follow the Google Docstring Style for consistency and readability.

• Classes:

  • Each class should have a docstring explaining its purpose and any unique attributes or methods. This docstring should summarize the role of the class in the module.

Specific Documentation Guidelines

1. Function-Level Documentation:

   • Include a brief docstring at the beginning of each function that explains:
     • Parameters: List and explain the function’s input parameters.
     • Returns: Describe the data returned by the function.
     • Raises: Detail any exceptions that the function might raise.
   • Example:

     def process_data(data: list) -> dict:
         """
         Processes input data and returns a dictionary of results.
     
         Args:
             data (list): List of data points to be processed.
     
         Returns:
             dict: Processed results including mean and standard deviation.
     
         Raises:
             ValueError: If data is not a list of numbers.
         """
     

2. Class-Level Documentation:

   • Use class-level docstrings to summarize the purpose and usage of the class.
   • Example:

     class DataProcessor:
         """
         Class for processing and analyzing data.
     
         This class provides methods for statistical analysis and
         data transformation. Suitable for numerical data inputs.
     
         Attributes:
             data (list): List of numerical data.
         """
     

3. In-Line Comments:

   • Use in-line comments sparingly and only to clarify complex logic or non-standard decisions in the code.
   • Avoid obvious comments; instead, focus on why something is done rather than what is being done.

API Documentation Standards

For code that interfaces with external services or shared modules, follow these standards for documenting APIs:

• Endpoints: Clearly list each endpoint and its purpose in the API documentation.
• Parameters: Define all required and optional parameters, including data types and default values.
• Response Format: Describe the structure and data types returned by each endpoint.
• Error Handling: Document possible error codes or messages and recommended solutions for common issues.
• Usage Examples: Provide examples showing both requests and responses to illustrate expected usage.

API documentation should be added to the docs/ManPages/api directory. Where possible, maintain consistency with other project documentation.

Documentation Updates with Pull Requests

Whenever a pull request (PR) introduces new features, refactors existing code, or modifies functionality, relevant documentation files must be updated accordingly. Contributors are responsible for ensuring that:

• All impacted README.md files, both module-specific and global, reflect the latest changes.
• Necessary updates to docstrings, function comments, and inline comments are made to maintain clarity and usability.

Footnote: This process is currently noted for future enforcement once the overarching program is complete.