Proposal for Documentation Versioning

[keraron]

The Issue

Currently the documentation of the various components is not versioned, once we update the docs for SLIM or Directory, the previous versions documentation is gone.

Since these components are being released at different intervals, we need to implement separate versioning for each component.

MkDocs does not support multiple versions under the same website.

The Proposed Solution

Split up the documentation, so each component has it's own website that supports versioning.

• docs.agntcy.org would remain as the main page with the Introduction, Getting Started, CSIT, Glossary, and Contributing Guide.
• docs.agntcy would become a landing page with links to navigate to the different components' documentation
• Documentation for OASF, Directory, SLIM, Identity, and Obs/Eval would be moved to <component>.agntcy.org.
• Each components' documentation would live in the component's repo agntcy/<component>/docs
• All sites would have the same style, layout, and configuration.
• Navigation buttons could be added to the header to switch between docs sites.

Pros

• Independent versioning for each component.
• Each team owns its docs repo/site.
• Smaller sites (the sidebar is getting more and more crowded).

Cons

• No unified search across the different components.
• More infrastructure to manage and upkeep.
• There may be content that needs to be present in multiple sites.
• Migration

Please share your thoughts and opinions :)

[ramizpolic]

How does this solve the versioning? I do not see anywhere a version selector here.

Each components' documentation would live in the component's repo agntcy//docs

if we want to include the versioning, then each component needs to agntcy/<component>/<tag>/docs
do note that there is one problem here -- if the docs server introduces a breaking change that requires changes to the previous component documentation, this won't be possible. if we have only markdown files, then it should be okay

[keraron]

With mike I think this is solved, we only need to keep the current version in main

[ramizpolic]

that does seem to solve everything 👍

[msardara]

I am in favor of this solution. Regarding the cons:

• No unified search across the different components -> This is currently in the mkdocs backlog: Search: cross-site search federation squidfunk/mkdocs-material#5230
• More infrastructure to manage and upkeep -> As the docs lives in the corresponding repo, each repo can have its own github page
• There may be content that needs to be present in multiple sites -> We put it in the federated central docs
• Migration -> This is gonna hurt:) - we need to setup a set of redirects