Example: a documentation repository structure

Worked example

This is a finished illustration to study, not a template - every repository’s exact needs differ. For the underlying decision, see the repository and a single repository?.

Layout

docs-repo/
├── src/
│   ├── content/
│   │   ├── en/
│   │   │   ├── getting-started/
│   │   │   │   ├── index.md
│   │   │   │   ├── installation.md
│   │   │   │   └── first-project.md
│   │   │   ├── guides/
│   │   │   │   └── ...
│   │   │   └── reference/
│   │   │       └── ...
│   │   └── fr/
│   │       └── <mirrors the en/ tree>
│   ├── components/         # reusable page components
│   └── assets/              # images referenced from content
├── scripts/                  # build-time automation (redirects, search index, etc.)
├── tests/                    # automated checks on the built output
├── config-file               # site/build configuration
└── package-manifest

Why this shape

• Locale is the top-level split, not a suffix on each filename (installation.md / installation.fr.md). This keeps each language a complete, independently navigable tree - see translation on why language-first organization simplifies branching for parallel translation work.
• Content is grouped by reader intent (getting-started/, guides/, reference/), not by internal team structure or by which product team owns a page. Readers navigate by what they’re trying to do, not by your org chart.
• scripts/ and tests/ are separated from content/. A contributor fixing a typo never needs to look at build tooling, and a contributor changing the build never touches prose by accident.
• Assets live near the content tree, not in a single flat images/ folder with thousands of files - makes it obvious which images are still referenced when a page is deleted.

What doesn’t belong in this repository

• Generated output (built HTML, PDFs) - regenerate it in CI, don’t commitCommitA recorded snapshot of changes in a Git repository, with an author, a date, and a message explaining the change. Commits form the project history that branches start from and that reviewers and translators compare.View in glossary → it. A .gitignore entry, not a folder, is the right home for build artifacts.
• Secrets or credentials for any service the build touches (analytics keys, deploy tokens) - those belong in the CI/CDCI/CD (continuous integration and continuous delivery)Automation that checks every change as soon as it is submitted (continuous integration) and publishes the result once the checks pass (continuous delivery). In docs-as-code, a CI/CD pipeline builds the documentation, runs tests such as link and schema checks, and deploys the site.View in glossary → platform’s secret store, never in tracked files.
• Binary source files (see source format) - if a legacy asset must ship as binary, keep it small and treat it as an exception, not a pattern to repeat.

Next step

To see how a change moves through a repositoryRepositoryThe place where a documentation team keeps its sources: shared folders, a CMS database, or a version-control system such as Git, which also stores the complete history of every file.View in glossary → like this one, from branchBranchA parallel line of work in a version-control system: changes made on a branch stay isolated until they are reviewed and merged back into the main line, so several writers, releases or languages can progress at the same time.View in glossary → to published page, see the docs-as-code workflow example.