diff --git a/docs-standards/00-quickstart.md b/docs/README.md similarity index 100% rename from docs-standards/00-quickstart.md rename to docs/README.md diff --git a/docs-standards/01-general-guidelines.md b/docs/codex/README.md similarity index 100% rename from docs-standards/01-general-guidelines.md rename to docs/codex/README.md diff --git a/docs-standards/10-structure-the-content/01-document-types/api-quickstart.md b/docs/nomos/README.md similarity index 100% rename from docs-standards/10-structure-the-content/01-document-types/api-quickstart.md rename to docs/nomos/README.md diff --git a/docs-standards/10-structure-the-content/01-document-types/hybrid-topic.md b/docs/waku/README.md similarity index 100% rename from docs-standards/10-structure-the-content/01-document-types/hybrid-topic.md rename to docs/waku/README.md diff --git a/docs-standards/10-structure-the-content/01-document-types/troubleshooting.md b/manual/0-overview/README.md similarity index 100% rename from docs-standards/10-structure-the-content/01-document-types/troubleshooting.md rename to manual/0-overview/README.md diff --git a/docs-standards/10-structure-the-content/_index.md b/manual/1-design-the-information/README.md similarity index 100% rename from docs-standards/10-structure-the-content/_index.md rename to manual/1-design-the-information/README.md diff --git a/docs-standards/20-style-the-content/01-voice.md b/manual/1-design-the-information/document-types/api-quickstart.md similarity index 100% rename from docs-standards/20-style-the-content/01-voice.md rename to manual/1-design-the-information/document-types/api-quickstart.md diff --git a/docs-standards/10-structure-the-content/01-document-types/concept-help-me-to-understand.md b/manual/1-design-the-information/document-types/concept-help-me-to-understand.md similarity index 100% rename from docs-standards/10-structure-the-content/01-document-types/concept-help-me-to-understand.md rename to manual/1-design-the-information/document-types/concept-help-me-to-understand.md diff --git a/docs-standards/20-style-the-content/02-capitalization.md b/manual/1-design-the-information/document-types/hybrid-topic.md similarity index 100% rename from docs-standards/20-style-the-content/02-capitalization.md rename to manual/1-design-the-information/document-types/hybrid-topic.md diff --git a/docs-standards/10-structure-the-content/01-document-types/procedure-help-me-to-do.md b/manual/1-design-the-information/document-types/procedure-help-me-to-do.md similarity index 100% rename from docs-standards/10-structure-the-content/01-document-types/procedure-help-me-to-do.md rename to manual/1-design-the-information/document-types/procedure-help-me-to-do.md diff --git a/docs-standards/10-structure-the-content/01-document-types/quickstart-help-me-get-started.md b/manual/1-design-the-information/document-types/quickstart-help-me-get-started.md similarity index 100% rename from docs-standards/10-structure-the-content/01-document-types/quickstart-help-me-get-started.md rename to manual/1-design-the-information/document-types/quickstart-help-me-get-started.md diff --git a/docs-standards/10-structure-the-content/01-document-types/reference-help-me-to-remember.md b/manual/1-design-the-information/document-types/reference-help-me-to-remember.md similarity index 100% rename from docs-standards/10-structure-the-content/01-document-types/reference-help-me-to-remember.md rename to manual/1-design-the-information/document-types/reference-help-me-to-remember.md diff --git a/docs-standards/20-style-the-content/03-titles.md b/manual/1-design-the-information/document-types/troubleshooting.md similarity index 100% rename from docs-standards/20-style-the-content/03-titles.md rename to manual/1-design-the-information/document-types/troubleshooting.md diff --git a/docs-standards/20-style-the-content/04-sentences-and-paragraphs.md b/manual/2-populate-the-structure/README.md similarity index 100% rename from docs-standards/20-style-the-content/04-sentences-and-paragraphs.md rename to manual/2-populate-the-structure/README.md diff --git a/examples/concept-example.md b/manual/2-populate-the-structure/canonical-examples/concept-example.md similarity index 100% rename from examples/concept-example.md rename to manual/2-populate-the-structure/canonical-examples/concept-example.md diff --git a/docs-standards/20-style-the-content/05-punctuation-and-symbols.md b/manual/2-populate-the-structure/llm/README.md similarity index 100% rename from docs-standards/20-style-the-content/05-punctuation-and-symbols.md rename to manual/2-populate-the-structure/llm/README.md diff --git a/manual/2-populate-the-structure/templates/README.md b/manual/2-populate-the-structure/templates/README.md new file mode 100644 index 0000000..8383a20 --- /dev/null +++ b/manual/2-populate-the-structure/templates/README.md @@ -0,0 +1,75 @@ +# Templates + +This directory contains templates to create new technical documents for Logos. Templates help maintain consistency and save time when creating similar types of content. + +- [Quickstart template](./quickstart-template.md) +- [Concept template](./concept-template.md) +- [Procedure template](./procedure-template.md) +- [Reference template](./reference-template.md) + +## Using templates + +Templates are Markdown files. To use a template, copy the desired template content and paste it into your new document. Then, fill in the relevant sections with your content. + +> **Note:** +> +> Your content should follow the structure and guidelines provided in the template. Don't modify the template to fit your content. If you need to update a template, send a pull request with your changes following the [contribution guidelines](../../CONTRIBUTING.md). + +## Guided vs. minimal templates + +The templates in this section use a guided approach, providing detailed instructions and examples to help you structure your content effectively. + +Unlike minimal templates, which offer only basic headings and leave much of the structure up to the author, guided templates are dense with content and may feel overwhelming at first. This initial density is intentional: it makes expectations explicit, prevents omissions, and typically shortens drafting and review time. + +The rationale for using guided templates instead of minimal templates is twofold: + +1. **Reduce context switching**: Minimize the need for authors to jump between resources (e.g., writing rules and examples) while drafting. Guided templates provide instructions and examples in one place. +2. **Support inexperienced authors**: SMEs are typically not trained as technical writers. For highly technical content that is not frequently updated, guided templates are the most effective way to help inexperienced authors produce complete and clear documentation. +This diagram illustrates this situation: + +```mermaid +%%{init: { + "theme": "base", + "themeVariables": { + "fontFamily": "Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto", + "fontSize": "14px", + "primaryTextColor": "#0f172a", + "lineColor": "#94a3b8" + }, + "flowchart": { "curve": "basis", "nodeSpacing": 50, "rankSpacing": 60 } +}}%% +flowchart LR + %% Groups + subgraph Inputs + direction TB + A{Doc
complexity?}:::decision + B{Writer
experience?}:::decision + E{Update
frequency?}:::decision + end + + subgraph Recommendation + direction TB + C([Lightweight
template]):::good + D([Feature-rich
template]):::strong + end + + %% Flows + A -- High --> B + A -- Low --> C + B -- New --> D + B -- Experienced --> C + E -- Often --> C + E -- Rare --> D + + %% (Optional) layout hint to keep Inputs aligned + A -. Align -.-> E + + %% Styles + classDef decision fill:#eff6ff,stroke:#3b82f6,stroke-width:1.5px,color:#0f172a; + classDef good fill:#ecfdf5,stroke:#10b981,stroke-width:1.5px,color:#064e3b; + classDef strong fill:#f5f3ff,stroke:#8b5cf6,stroke-width:1.5px,color:#2e1065; + + %% Link accents (green to "Lightweight", purple to "Feature-rich") + linkStyle 1,3,4 stroke:#10b981,stroke-width:1.5px; + linkStyle 2,5 stroke:#8b5cf6,stroke-width:1.5px; +``` diff --git a/templates/concept/concept-template.md b/manual/2-populate-the-structure/templates/concept-template.md similarity index 100% rename from templates/concept/concept-template.md rename to manual/2-populate-the-structure/templates/concept-template.md diff --git a/templates/concept/reference-template.md b/manual/2-populate-the-structure/templates/reference-template.md similarity index 100% rename from templates/concept/reference-template.md rename to manual/2-populate-the-structure/templates/reference-template.md diff --git a/templates/quickstart/template-quickstart.md b/manual/2-populate-the-structure/templates/template-quickstart.md similarity index 100% rename from templates/quickstart/template-quickstart.md rename to manual/2-populate-the-structure/templates/template-quickstart.md diff --git a/docs-standards/20-style-the-content/06-bullet-lists.md b/manual/3-validate-the-design/README.md similarity index 100% rename from docs-standards/20-style-the-content/06-bullet-lists.md rename to manual/3-validate-the-design/README.md diff --git a/docs-standards/20-style-the-content/07-numbered-lists.md b/manual/3-validate-the-design/linters/README.md similarity index 100% rename from docs-standards/20-style-the-content/07-numbered-lists.md rename to manual/3-validate-the-design/linters/README.md diff --git a/docs-standards/20-style-the-content/08-tables.md b/manual/3-validate-the-design/self-review/README.md similarity index 100% rename from docs-standards/20-style-the-content/08-tables.md rename to manual/3-validate-the-design/self-review/README.md diff --git a/docs-standards/20-style-the-content/09-units-of-measure.md b/manual/3-validate-the-design/sme-review/README.md similarity index 100% rename from docs-standards/20-style-the-content/09-units-of-measure.md rename to manual/3-validate-the-design/sme-review/README.md diff --git a/docs-standards/20-style-the-content/10-links.md b/manual/3-validate-the-design/writing-rules/README.md similarity index 100% rename from docs-standards/20-style-the-content/10-links.md rename to manual/3-validate-the-design/writing-rules/README.md diff --git a/docs-standards/20-style-the-content/11-ui-elements.md b/manual/3-validate-the-design/writing-rules/structure-the-content/README.md similarity index 100% rename from docs-standards/20-style-the-content/11-ui-elements.md rename to manual/3-validate-the-design/writing-rules/structure-the-content/README.md diff --git a/docs-standards/20-style-the-content/12-admonitions.md b/manual/3-validate-the-design/writing-rules/style-the-content/README.md similarity index 100% rename from docs-standards/20-style-the-content/12-admonitions.md rename to manual/3-validate-the-design/writing-rules/style-the-content/README.md diff --git a/docs-standards/20-style-the-content/_index.md b/manual/3-validate-the-design/writing-rules/style-the-content/admonitions.md similarity index 100% rename from docs-standards/20-style-the-content/_index.md rename to manual/3-validate-the-design/writing-rules/style-the-content/admonitions.md diff --git a/docs-standards/30-work-with-media/01-icons and emojis.md b/manual/3-validate-the-design/writing-rules/style-the-content/bullet-lists.md similarity index 100% rename from docs-standards/30-work-with-media/01-icons and emojis.md rename to manual/3-validate-the-design/writing-rules/style-the-content/bullet-lists.md diff --git a/docs-standards/30-work-with-media/02-images.md b/manual/3-validate-the-design/writing-rules/style-the-content/capitalization.md similarity index 100% rename from docs-standards/30-work-with-media/02-images.md rename to manual/3-validate-the-design/writing-rules/style-the-content/capitalization.md diff --git a/docs-standards/20-style-the-content/13-code.md b/manual/3-validate-the-design/writing-rules/style-the-content/code.md similarity index 100% rename from docs-standards/20-style-the-content/13-code.md rename to manual/3-validate-the-design/writing-rules/style-the-content/code.md diff --git a/docs-standards/30-work-with-media/03-diagrams.md b/manual/3-validate-the-design/writing-rules/style-the-content/links.md similarity index 100% rename from docs-standards/30-work-with-media/03-diagrams.md rename to manual/3-validate-the-design/writing-rules/style-the-content/links.md diff --git a/docs-standards/30-work-with-media/04-videos.md b/manual/3-validate-the-design/writing-rules/style-the-content/numbered-lists.md similarity index 100% rename from docs-standards/30-work-with-media/04-videos.md rename to manual/3-validate-the-design/writing-rules/style-the-content/numbered-lists.md diff --git a/docs-standards/30-work-with-media/_index.md b/manual/3-validate-the-design/writing-rules/style-the-content/punctuation-and-symbols.md similarity index 100% rename from docs-standards/30-work-with-media/_index.md rename to manual/3-validate-the-design/writing-rules/style-the-content/punctuation-and-symbols.md diff --git a/docs-standards/40-terminology/01-common.md b/manual/3-validate-the-design/writing-rules/style-the-content/sentences-and-paragraphs.md similarity index 100% rename from docs-standards/40-terminology/01-common.md rename to manual/3-validate-the-design/writing-rules/style-the-content/sentences-and-paragraphs.md diff --git a/docs-standards/40-terminology/02-waku.md b/manual/3-validate-the-design/writing-rules/style-the-content/tables.md similarity index 100% rename from docs-standards/40-terminology/02-waku.md rename to manual/3-validate-the-design/writing-rules/style-the-content/tables.md diff --git a/docs-standards/40-terminology/03-codex.md b/manual/3-validate-the-design/writing-rules/style-the-content/titles.md similarity index 100% rename from docs-standards/40-terminology/03-codex.md rename to manual/3-validate-the-design/writing-rules/style-the-content/titles.md diff --git a/docs-standards/40-terminology/_index.md b/manual/3-validate-the-design/writing-rules/style-the-content/ui-elements.md similarity index 100% rename from docs-standards/40-terminology/_index.md rename to manual/3-validate-the-design/writing-rules/style-the-content/ui-elements.md diff --git a/manual/3-validate-the-design/writing-rules/style-the-content/units-of-measure.md b/manual/3-validate-the-design/writing-rules/style-the-content/units-of-measure.md new file mode 100644 index 0000000..e69de29 diff --git a/manual/3-validate-the-design/writing-rules/style-the-content/voice.md b/manual/3-validate-the-design/writing-rules/style-the-content/voice.md new file mode 100644 index 0000000..e69de29 diff --git a/manual/3-validate-the-design/writing-rules/terminology/README.md b/manual/3-validate-the-design/writing-rules/terminology/README.md new file mode 100644 index 0000000..e69de29 diff --git a/manual/3-validate-the-design/writing-rules/terminology/codex-terminology.md b/manual/3-validate-the-design/writing-rules/terminology/codex-terminology.md new file mode 100644 index 0000000..e69de29 diff --git a/manual/3-validate-the-design/writing-rules/terminology/common-terminology.md b/manual/3-validate-the-design/writing-rules/terminology/common-terminology.md new file mode 100644 index 0000000..e69de29 diff --git a/manual/3-validate-the-design/writing-rules/terminology/nomos-terminology.md b/manual/3-validate-the-design/writing-rules/terminology/nomos-terminology.md new file mode 100644 index 0000000..e69de29 diff --git a/manual/3-validate-the-design/writing-rules/terminology/waku-terminology.md b/manual/3-validate-the-design/writing-rules/terminology/waku-terminology.md new file mode 100644 index 0000000..e69de29 diff --git a/manual/3-validate-the-design/writing-rules/work-with-media/README.md b/manual/3-validate-the-design/writing-rules/work-with-media/README.md new file mode 100644 index 0000000..e69de29 diff --git a/manual/3-validate-the-design/writing-rules/work-with-media/diagrams.md b/manual/3-validate-the-design/writing-rules/work-with-media/diagrams.md new file mode 100644 index 0000000..e69de29 diff --git a/manual/3-validate-the-design/writing-rules/work-with-media/icons-and-emojis.md b/manual/3-validate-the-design/writing-rules/work-with-media/icons-and-emojis.md new file mode 100644 index 0000000..e69de29 diff --git a/manual/3-validate-the-design/writing-rules/work-with-media/images.md b/manual/3-validate-the-design/writing-rules/work-with-media/images.md new file mode 100644 index 0000000..e69de29 diff --git a/manual/3-validate-the-design/writing-rules/work-with-media/videos.md b/manual/3-validate-the-design/writing-rules/work-with-media/videos.md new file mode 100644 index 0000000..e69de29 diff --git a/manual/4-integrate-the-content/README.md b/manual/4-integrate-the-content/README.md new file mode 100644 index 0000000..e69de29 diff --git a/manual/4-integrate-the-content/build-and-publish/README.md b/manual/4-integrate-the-content/build-and-publish/README.md new file mode 100644 index 0000000..e69de29 diff --git a/manual/4-integrate-the-content/content-model/README.md b/manual/4-integrate-the-content/content-model/README.md new file mode 100644 index 0000000..e69de29 diff --git a/manual/README.md b/manual/README.md new file mode 100644 index 0000000..e69de29 diff --git a/templates/concept/concept-example.md b/templates/concept/concept-example.md deleted file mode 100644 index dcdbcf7..0000000 --- a/templates/concept/concept-example.md +++ /dev/null @@ -1 +0,0 @@ -# Concept example