Skip to main content

126. Automated FDD Collection

Status: Accepted Date: 2025-07-06

Context​

Our monorepo uses Feature-Driven Development (FDD) as a core design practice. Every module and significant component has an FDD.md file located at its root. For our documentation to be complete, these FDDs must be included in the toma developer portal.

Manually creating a sidebar entry and a documentation page for every FDD would be tedious, error-prone, and unsustainable. As new modules are added, developers would have to remember to update the documentation sidebar, which they would inevitably forget. This would lead to the documentation becoming out of sync with the codebase.

Decision​

We will implement an automated FDD collection system. This will be built as a custom Docusaurus plugin.

Before the Docusaurus build process runs, this plugin will:

  1. Scan the entire monorepo filesystem for files matching the **/*.fdd.md and **/FDD.md glob patterns.
  2. For each FDD file found, it will read its frontmatter to get its fddId and other metadata.
  3. It will then dynamically generate a virtual documentation page for that FDD.
  4. Finally, it will automatically generate the sidebar navigation structure based on the file paths of the FDDs, mirroring the monorepo's directory structure.

This ensures that any FDD file, anywhere in the repository, is automatically discovered, rendered, and included in the documentation site's navigation without any manual configuration.

Consequences​

Positive:

  • Zero-Maintenance Documentation: Developers can add new modules with FDDs, and the documentation will update automatically. There is no manual step to remember. This drastically reduces friction and ensures the documentation is always complete.
  • Single Source of Truth: The FDD file in the module's directory is the single source of truth. There is no copy of the content in the documentation site's source.
  • Mirrors Code Structure: The documentation navigation will naturally mirror the structure of the monorepo, making it intuitive for developers to find the FDD for a specific module.

Negative:

  • Custom Plugin Maintenance: We are now responsible for maintaining a custom Docusaurus plugin. If Docusaurus releases a new major version with breaking API changes, we will need to update our plugin.
  • Build-Time Complexity: This adds a custom, complex step to the start of the documentation build process. A bug in the collection script could break the entire documentation build.
  • Magic/Implicit Behavior: The process is somewhat "magic". A developer might not immediately understand how the FDDs are appearing on the site without knowing about this custom plugin.

Mitigation:

  • Targeted Plugin Scope: The plugin has a very specific and well-defined responsibility. It is not overly complex, and its surface area of interaction with the Docusaurus API is small, which should make future updates manageable.
  • Robust Error Handling: The collection script will be written with robust error handling. If it fails to process a single FDD, it should log the error and skip that file, rather than crashing the entire build.
  • Good Internal Documentation: The existence and purpose of this plugin will be well-documented within the platform/docs module itself, ensuring that developers who need to work on the documentation system can understand how it works.