Mapping Your Docs-as-Code Repo: Navigating Architectural Evolution of Repositories
summary
Maps and compares four concrete repo patterns tested at scale and when each actually succeeds: Public-Private Mirror (keeps unreleased content private but adds sync overhead and merge conflicts), Multi-Branch Single-Sourcing (one repo, branch-per-version, good for small diffs, painful with dozens of branches), File-System Symlinks (saves storage, OS-dependent), and Shared Git Subdirectories (single source-of-truth for common files, one bad change breaks many repos). Trade-offs, ownership, and access requirements determine the choice.
AI-written summary · about
chapters (15)
- 0:00Introduction
- 1:28Engineers vs docs teams needs
- 2:52Key questions for docs placement
- 4:16Initial repo architecture options
- 8:09Limitations of single solutions
- 8:30Public private mirror pattern
- 10:36Multibranching single sourcing
- 12:01Sharing assets with symlinks
- 13:45Shared Git subdirectories
- 15:30Takeaways for docs architecture
- 17:44Q&A
- 19:10Horror stories and pitfalls
- 20:14Git submodules and shared repos
- 21:17Pivoting teams to Docs-as-Code
- 22:20Closing remarks
related talks
07mGit strategies for documentation
09mLightning Talk: Best Practices on Organizing GitOps Repositories
24mBuilding your ideal codebase: monorepos & multirepos living in harmony
46mExploring the power of monorepos: When and why to use them
21mGit submodules: we have monorepo at home
35mThe Git you don't know
19mEscaping Chaos: Strategies to Move from Polyrepo to Monorepo
46mGit Workflow Etiquette: Repository Organization for Clean Codebases