Re-org content in repository

[jorge-campo]

To keep writing and adding the OneDoc project deliverables, we need a clear repository structure. This structure won't be static and change as we add more deliverables and work on different parts of the project. The proposed structure is a good start, so we can keep the project going without spending too much time in thinking where each content goes in the repo.

This structure proposes the OneDoc project deliverables as different chapters of a technical writing manual.

Here’s a monorepo scaffolding that cleanly separates the technical‑writing manual from the three product documentation sets (Waku, Nomos, Codex) and bakes in your four stages (1–4) and artifacts (A–F).

ASCII layout:

logos-docs/
├─ README.md                              # Repo overview + contribution quickstart
├─ LICENSE
├─ CODE_OF_CONDUCT.md
├─ CONTRIBUTING.md
├─ SECURITY.md
├─ scripts/
│  ├─ build-docs.sh
│  ├─ lint-docs.sh
│  ├─ validate-content-model.sh
│  └─ sync-gitbook.sh
├─ .github/
│  ├─ pull_request_template.md            # PR checklist shortcuts (Stage 3/5)
│  ├─ ISSUE_TEMPLATE/
│  │  ├─ doc-request.yml
│  │  └─ bug-report.yml
│  └─ workflows/
│     ├─ docs-ci.yml                      # builds, link-checks, Vale/markdownlint
│     ├─ lint.yml
│     └─ publish-preview.yml              # PR previews (e.g., to a static preview)
│
├─ manual/                                # The technical writing manual (NOT product docs)
│  ├─ README.md                           # How to use the manual; map of stages A–F, 1–6
│  ├─ 0-overview/
│  │  └─ README.md                        # Principles, doc types, style baseline
│  ├─ 1-designing-information/            # Stage 1
│  │  ├─ README.md                        # Goal: “How should I organize the information?”
│  │  ├─ task-analysis/                   # (A)
│  │  │  ├─ README.md
│  │  │  ├─ task-analysis-template.md
│  │  │  ├─ task-analysis.form.yaml
│  │  │  └─ examples/
│  │  │     ├─ waku-task-analysis.md
│  │  │     └─ nomos-task-analysis.md
│  │  ├─ block-model/                     # DITA-like building blocks
│  │  │  ├─ README.md
│  │  │  ├─ concept.md
│  │  │  ├─ procedure.md
│  │  │  ├─ reference.md
│  │  │  └─ troubleshooting.md
│  │  └─ organization-blueprints/         # (B)
│  │     ├─ README.md
│  │     ├─ blueprint-template.md
│  │     └─ examples/
│  ├─ 2-populating-structure/             # Stage 2
│  │  ├─ README.md                        # “What content do I need to write?”
│  │  ├─ templates/                       # (C)
│  │  │  ├─ README.md
│  │  │  ├─ concept-template.md
│  │  │  ├─ procedure-template.md
│  │  │  ├─ reference-template.md
│  │  │  └─ troubleshooting-template.md
│  │  ├─ canonical-examples/              # (F)
│  │  │  ├─ README.md
│  │  │  ├─ waku-example-concept.md
│  │  │  └─ codex-example-procedure.md
│  │  ├─ sources/                         # (E) core tech info inventory
│  │  │  ├─ README.md
│  │  │  ├─ source-inventory-template.md
│  │  │  └─ source-log.md
│  │  └─ llm/                             # (3)
│  │     ├─ README.md
│  │     ├─ prompt-recipes.md
│  │     ├─ guardrails.md
│  │     └─ prompts/
│  │        ├─ first-draft.md
│  │        ├─ task-analysis-to-blueprint.md
│  │        └─ tighten-style.md
│  ├─ 3-validating-design/                # Stage 3
│  │  ├─ README.md                        # Self-review + SME review
│  │  ├─ self-review/
│  │  │  ├─ README.md
│  │  │  ├─ checklists/
│  │  │  │  ├─ author-checklist.md
│  │  │  │  └─ definition-of-done.md
│  │  │  └─ writing-rules.md              # (D)
│  │  ├─ linters/
│  │  │  ├─ README.md
│  │  │  ├─ vale/.vale.ini
│  │  │  ├─ vale/Styles/Logos/Rules.yml
│  │  │  ├─ markdownlint/.markdownlint.jsonc
│  │  │  └─ link-check/config.json
│  │  └─ review-process/
│  │     ├─ README.md
│  │     ├─ pr-checklist.md
│  │     ├─ pr-labels.md
│  │     └─ sme-review-guide.md           # (5)
│  └─ 4-integrating-into-structure/       # Stage 4
│     ├─ README.md                        # “Where does this new content fit?”
│     ├─ content-model/                   # (E)
│     │  ├─ README.md
│     │  ├─ metadata-schema.json          # front-matter schema
│     │  ├─ toc-rules.md
│     │  └─ navigation-examples/
│     └─ build-and-publish/               # (6)
│        ├─ README.md
│        ├─ gitbook/
│        │  ├─ publishing-guide.md
│        │  └─ space-mapping.md           # repo path -> GitBook Space
│        └─ github-actions/
│           └─ examples.yml
│
└─ docs/                                   # Product documentation (publishable)
   ├─ _shared/
   │  ├─ README.md
   │  ├─ assets/
   │  └─ snippets/
   ├─ waku/
   │  ├─ README.md                         # Project landing page (GitBook root)
   │  ├─ SUMMARY.md                        # GitBook ToC for Waku
   │  ├─ content-model.yaml                # IA + nav config for validation/CI
   │  ├─ concepts/
   │  ├─ procedures/
   │  ├─ references/
   │  ├─ troubleshooting/
   │  ├─ api/
   │  ├─ release-notes/
   │  └─ assets/
   ├─ nomos/
   │  ├─ README.md
   │  ├─ SUMMARY.md
   │  ├─ content-model.yaml
   │  ├─ concepts/
   │  ├─ procedures/
   │  ├─ references/
   │  ├─ troubleshooting/
   │  ├─ api/
   │  ├─ release-notes/
   │  └─ assets/
   └─ codex/
      ├─ README.md
      ├─ SUMMARY.md
      ├─ content-model.yaml
      ├─ concepts/
      ├─ procedures/
      ├─ references/
      ├─ troubleshooting/
      ├─ api/
      ├─ release-notes/
      └─ assets/

Explanation

Why this organization

• Clear separation of concerns: manual/ is the how; docs/ is the what. That prevents mixing guidance assets (templates, prompts, linters, checklists) with the actual customer‑facing content for Waku/Nomos/Codex.
• Mirrors the four-stage workflow: each stage has its own folder with its inputs/outputs, so contributors always know where to start and what “done” looks like for that stage.
• Carries A–F artifacts through the structure: task-analysis (A), organization-blueprints (B), templates (C), writing-rules/linters (D), sources/content-model (E), and canonical-examples (F).
• Ready for GitBook: each project folder under docs/ contains a README.md (landing) and SUMMARY.md (table of contents). That allows publishing each project as its own GitBook Space without dragging in the manual.
• CI- and review-friendly: .github/workflows runs Vale/markdownlint/link-check across changed files; PR templates/checklists in manual/3-validating-design/ and .github/ encode the review process and Definition of Done.
• Reuse with boundaries: docs/_shared hosts cross‑project assets and snippets; each project also has its own assets/ to keep binary files close to their pages.
• Content model as code: content-model.yaml and metadata-schema.json let CI validate front‑matter, taxonomy, and ToC consistency before publishing.
• Developer‑first ergonomics: scripts like lint-docs.sh and build-docs.sh give a one‑command local workflow; folder names and templates match the block types developers will author.

Why README.md in every “manual” section?

• Fast orientation: when you click into any folder on GitHub, README.md renders automatically. It serves as the section’s landing page, telling authors the purpose, inputs, outputs, and how to use the files inside.
• Encodes the contract for “done”: each section README lists goals, entry/exit criteria, and links to the exact templates, checklists, and scripts to run. That turns the manual into a guided workflow rather than a pile of files.
• Reduces ramp‑up time: new contributors don’t need to know the whole repo—every folder locally explains itself and points to the next step.
• Supports automation and docs generation: section READMEs can be stitched into a single manual or internal site; they provide stable anchors for scripts that build navigation or training material.
• Improves PR reviews: reviewers land on a concise guide for the section, with links to the Definition of Done and linters to run; this cuts back-and-forth and standardizes expectations.
• Minimizes drift: each README declares scope and ownership for the folder, making it clearer who maintains what and when to update examples or rules.
• Consistent with GitBook/GitHub behavior: README.md is the default index both in GitHub’s UI and in many static doc pipelines; using it keeps navigation predictable online and locally.