Proposal for Open Source documentation

[thallgren]

Backround

The documentation for the Open Source version of Telepresence is currently hosted in a private GitHub repository within the Datawire organization. This limits the open source community's ability to contribute to the documentation and prevents maintainers outside of Ambassador Labs from participating in its maintenance. To address these limitations, this proposal suggests relocating the documentation to public repositories under the Telepresence organization.

Proposal

Location

I propose housing the documentation alongside the source code within a dedicated /docs folder in the main telepresence repository. This ensures that the documentation remains with its corresponding codebase, always reflecting the current and evolving state of the project. Additionally, this approach preserves the complete version history of the documentation. From a versioning standpoint, the documentation will utilize the same branches and tags as the codebase since it resides within the same repository.

Presentation

The documentation can be presented through the separate telepresence.io repository. This repository will be cleared of its currently existing, outdated documentation releases (currently ending at version 2.5). Subsequently, a CI build script will be implemented. This script will automatically execute a git read-tree --prefix docs/<branch name> -u telepresence/<branch name>:docs command for each release branch in the telepresence repository containing the /docs folder. In simpler terms, the script will create a dedicated folder within the telepresence.io repository for each release branch in the main repository, containing a read-only copy of the corresponding documentation. This will essentially mirror the current structure of the documentation repository, with the key difference being that all versions will be generated and read-only within the telepresence.io repository.

Older versions

We include a text informing the user that documentation for older versions of Telepresence can be found at their current location at getambassador.io.

[thallgren]

Ping @njayp @P0lip @kai-tillman

[github-actions]

This issue is stale because it has been open 60 days with no activity. Remove stale label or comment, or this will be closed in 7 days.

[thallgren]

This ticket has mostly been implemented now, but the process is not yet fully automated.