From 7d92b5feb921a233b62da3a136755d2f56eda442 Mon Sep 17 00:00:00 2001 From: Jorge <62282406+jorge-campo@users.noreply.github.com> Date: Tue, 12 Aug 2025 17:20:52 +0200 Subject: [PATCH 1/3] documentation guide -- first draft, not ready for review --- .../00-end-to-end-documentation-guide.md | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs-standards/00-end-to-end-documentation-guide.md diff --git a/docs-standards/00-end-to-end-documentation-guide.md b/docs-standards/00-end-to-end-documentation-guide.md new file mode 100644 index 0000000..6555c15 --- /dev/null +++ b/docs-standards/00-end-to-end-documentation-guide.md @@ -0,0 +1,56 @@ +# End-to-end-documentation guide + +This guide is for the subject-matter experts (SMEs) who build our products: the developers, infrastructure engineers, and other technical contributors responsible for designing and implementing features. It is written for technical experts who need to produce clear, effective documentation for the solutions they create, but who are not professional technical writers. + +Our core assumption is that the primary barrier to writing documentation is not a lack of willingness, but the lack of a clear and repeatable process. This guide provides that process. It is designed to remove the guesswork, eliminate "blank page" anxiety, and give you a straightforward workflow to create high-quality documentation consistently. + +## How this guide is organized + +This document provides a high-level overview of the entire documentation workflow, presented as a sequence of five distinct stages: task analysis, good-enough first draft, review and refinement, and publication. It is designed to be a map that you can use to navigate the process from an initial idea to a final, published document. + +This document does not contain exhaustive details. Instead, it functions as a central hub, providing direct links to the specific templates, checklists, writing rules, and external tools required to complete each step of the process. You can use it as a quick reference to find the resources you need for a specific task. + +## The documentation workflow + +This guide provides an end-to-end overview of the documentation process, from initial analysis to final publication. Use it to understand each part of the workflow and how they connect. + +## Task analysis + +| Element | Description | +|:--------|:------------| +| Description | (1) Identify and decompose SME's goal
(2) Combine topics into documents | +| Goal | Define scope and structure before writing to ensure alignment with SME's goal | +| Input | Feature code, user stories, and any other existing documentation | +| Output | The name of the document(s) that describes the feature with basic headings 2 (H2) outline | +| Tools | - Task analysis guide
- Topic combination rules | + + +## Good-enough first draft + +| Element | Description | +|:--------|:------------| +| Description | Create a good-enough first draft (9) by prompting (6) an LLM (3) with relevant context (4, 5, 7) and examples (8). | +| Goal | Reduce the time required to document new features by supporting the process with LLMs | +| Input | - The H2 outline from the task analysis stage.
- Contextual information (4, 5, 7).
- Writing rules and examples (8). | +| Output | A "good-enough" first draft (9) of the document(s) generated by the LLM. | +| Tools | LLM (3).
- A pre-defined prompt (6). | + +## Review and refinement + +| Element | Description | +|:--------|:------------| +| Description | Review the good-enough first draft (9) using the review checklist (10). Refine it by self-review (11) and incorporating feedback to create the final documents (12) | +| Goal | Improve the quality and completeness of the documentation before final delivery. | +| Input | Good-enough first draft (9). | +| Output | The final version of the document(s) that describes the feature with a comprehensive outline and detailed content. | +| Tools | - Review checklist
- Feedback collection via GitHub pull request | + +## Publication + +| Element | Description | +|:--------|:------------| +| Description | Publish the final version of the document(s) in the table of contents. | +| Goal | Make the documentation publicly available and easily discoverable. | +| Input | Final version of the document(s) (12). | +| Output | Published documentation that is accessible to users. | +| Tools | - Content model
- Documentation publishing platform | From 70dc645131ba1a1752b64cfd0af1be52e0719409 Mon Sep 17 00:00:00 2001 From: Jorge <62282406+jorge-campo@users.noreply.github.com> Date: Wed, 20 Aug 2025 11:33:16 +0200 Subject: [PATCH 2/3] (#44) add Mermaid diagrams for workflow stages 1-4 --- .../00-end-to-end-documentation-guide.md | 175 ++++++++++++++---- 1 file changed, 142 insertions(+), 33 deletions(-) diff --git a/docs-standards/00-end-to-end-documentation-guide.md b/docs-standards/00-end-to-end-documentation-guide.md index 6555c15..c9ea9b6 100644 --- a/docs-standards/00-end-to-end-documentation-guide.md +++ b/docs-standards/00-end-to-end-documentation-guide.md @@ -1,56 +1,165 @@ -# End-to-end-documentation guide +# End-to-end documentation guide -This guide is for the subject-matter experts (SMEs) who build our products: the developers, infrastructure engineers, and other technical contributors responsible for designing and implementing features. It is written for technical experts who need to produce clear, effective documentation for the solutions they create, but who are not professional technical writers. +This guide is for the subject-matter experts (SMEs) who contribute to our products: the developers, infrastructure engineers, and other technical contributors responsible for designing and implementing features. It is written for technical experts who need to produce clear, effective documentation for the solutions they create, but who are not professional technical writers. -Our core assumption is that the primary barrier to writing documentation is not a lack of willingness, but the lack of a clear and repeatable process. This guide provides that process. It is designed to remove the guesswork, eliminate "blank page" anxiety, and give you a straightforward workflow to create high-quality documentation consistently. +Our core assumption is that the primary barrier to writing documentation is not a lack of willingness, but the lack of a clear and repeatable process. This guide provides that process. It is designed to remove ambiguity, eliminate "blank page" anxiety, and provide a predictable workflow to create high-quality documentation consistently. ## How this guide is organized -This document provides a high-level overview of the entire documentation workflow, presented as a sequence of five distinct stages: task analysis, good-enough first draft, review and refinement, and publication. It is designed to be a map that you can use to navigate the process from an initial idea to a final, published document. +This document provides a high-level overview of the documentation workflow, presented as a sequence of four distinct stages: designing the information, populating the content structure, validating the design, and integrating into the overall structure. It is designed to be a map that you can use to navigate the process from an initial idea to a final, published document. This document does not contain exhaustive details. Instead, it functions as a central hub, providing direct links to the specific templates, checklists, writing rules, and external tools required to complete each step of the process. You can use it as a quick reference to find the resources you need for a specific task. ## The documentation workflow -This guide provides an end-to-end overview of the documentation process, from initial analysis to final publication. Use it to understand each part of the workflow and how they connect. +This guide provides an end-to-end overview of the documentation process, from initial analysis to final integration. Use it to understand each part of the workflow and how they connect. -## Task analysis +## Stage 1: Designing the information | Element | Description | |:--------|:------------| -| Description | (1) Identify and decompose SME's goal
(2) Combine topics into documents | -| Goal | Define scope and structure before writing to ensure alignment with SME's goal | -| Input | Feature code, user stories, and any other existing documentation | -| Output | The name of the document(s) that describes the feature with basic headings 2 (H2) outline | -| Tools | - Task analysis guide
- Topic combination rules | - - -## Good-enough first draft +| Description | Identify the reader’s goal, perform a guided task analysis, and decompose the goal into core information blocks (Concept, Procedure, Reference, Troubleshooting). Organize these blocks into a structural blueprint. | +| Goal | Define scope and structure before writing, ensuring alignment with the reader’s goal. | +| Input | Feature code, user stories, and any other existing documentation. | +| Output | A content organization plan (blueprint) that specifies what documents are needed and how information will be structured. | +| Tools | - Task analysis template
- Information block organization rules | + +```mermaid +flowchart LR + %% Main flow + A[Reader's goal] -->|Task analysis| B((1 Task analysis)) + B --> C[Identify information blocks] + C --> D[Concept] + C --> E[Procedure] + C --> F[Reference] + C --> G[Troubleshooting] + C -->|Organize| H((2 Organize)) + H --> I[Structural blueprint] + + %% Supporting tools + J[Task analysis template] --> B + K[Block organization rules] --> H + + %% Questions + J -.-> JA["A: 'How do I break down the reader's goal?'"] + K -.-> KB["B: 'How do I organize the information?'"] + + %% Styling + style B fill:#fdd,stroke:#333,stroke-width:1px + style H fill:#fdd,stroke:#333,stroke-width:1px + style JA fill:#bbf,stroke:#333,stroke-width:1px + style KB fill:#bbf,stroke:#333,stroke-width:1px +``` + +## Stage 2: Populating the content structure | Element | Description | |:--------|:------------| -| Description | Create a good-enough first draft (9) by prompting (6) an LLM (3) with relevant context (4, 5, 7) and examples (8). | -| Goal | Reduce the time required to document new features by supporting the process with LLMs | -| Input | - The H2 outline from the task analysis stage.
- Contextual information (4, 5, 7).
- Writing rules and examples (8). | -| Output | A "good-enough" first draft (9) of the document(s) generated by the LLM. | -| Tools | LLM (3).
- A pre-defined prompt (6). | - -## Review and refinement +| Description | Translate the blueprint into a "good-enough" first draft by filling predefined templates with content drawn from technical sources. Use canonical examples and, where useful, LLMs to assist in generating text. | +| Goal | Produce a "good-enough" first draft that matches the designed structure and reduces ambiguity in what needs to be written. | +| Input | Structural blueprint from Stage 1, technical notes, repository content, templates, and examples. | +| Output | A structured "good-enough" draft of the required document(s). | +| Tools | - Templates
- Canonical examples
- Writing rules
- Custom prompts for LLM assistance | + +```mermaid +flowchart LR +%% Stage 2 (Populating the content structure) + +subgraph S1[ ] + direction LR + Stage1[Stage 1]:::stage + SB[Structural blueprint]:::artifact + Stage1 -. from Stage 1 .-> SB +end + +T["Standardized templates"]:::artifact --> CP +W["Writing rules"]:::artifact --> CP +I["Core technical information (notes + repos)"]:::artifact --> CP +X["Canonical examples"]:::artifact --> CP +SB --> CP + +CP[[Custom prompts]]:::prompt --> LLM +LLM[(LLM)]:::process --> GD["Good-enough first draft"]:::output + +%% Styles +classDef artifact fill:#FFF7D6,stroke:#333,stroke-width:1px; %% pale yellow +classDef prompt fill:#E3F2FF,stroke:#333,stroke-width:1px; %% pale blue, distinct shape +classDef process fill:#EFEFEF,stroke:#333,stroke-width:1px; +classDef output fill:#FFFFFF,stroke:#333,stroke-width:1px; +classDef stage fill:#FFFFFF,stroke-dasharray:3 3,stroke:#777; %% dotted outline for Stage 1 box +``` + +## Stage 3: Validating the design | Element | Description | |:--------|:------------| -| Description | Review the good-enough first draft (9) using the review checklist (10). Refine it by self-review (11) and incorporating feedback to create the final documents (12) | -| Goal | Improve the quality and completeness of the documentation before final delivery. | -| Input | Good-enough first draft (9). | -| Output | The final version of the document(s) that describes the feature with a comprehensive outline and detailed content. | -| Tools | - Review checklist
- Feedback collection via GitHub pull request | - -## Publication +| Description | Improve and refine the draft through self-review, applying checklists, writing rules, and linters. Incorporate additional content as needed. Submit the draft in a GitHub pull request, where SMEs review for technical accuracy and confirm that the content effectively supports the user. | +| Goal | Ensure the documentation is accurate, complete, and structured according to the design. | +| Input | "good-enough" draft from Stage 2. | +| Output | Reviewed and refined documentation, technically validated and structurally consistent. | +| Tools | - Review checklists
- Writing rules
- Linters
- GitHub pull request review | + +```mermaid +flowchart LR + subgraph Stage3["Stage 3: Review & Refinement"] + GD["Good-enough first draft"] --> SR["Self-review"] --> SD["Second draft"] --> SME["SME review"] --> FC["Final content"] + + %% Supporting tools feeding into Self-review + RC["Review checklist"] --> SR + WR["Writing rules"] --> SR + Lint["Linter"] --> SR + + %% Pull request connected to SME review + PR["Pull request"] -.-> SME + end + + %% Dotted line from Stage 2 + Stage2["Stage 2"] -.-> GD + + classDef main fill:#fff,stroke:#333,stroke-width:2px + classDef support fill:#eef,stroke:#333,stroke-dasharray: 3 3 + classDef review fill:#fdd,stroke:#c33,stroke-width:2px + classDef stage fill:#ddd,stroke:#333,stroke-dasharray: 5 5 + + class GD,SD,FC main + class RC,WR,Lint,PR support + class SR,SME review + class Stage2 stage +``` + +## Stage 4: Integrating into the overall structure | Element | Description | |:--------|:------------| -| Description | Publish the final version of the document(s) in the table of contents. | -| Goal | Make the documentation publicly available and easily discoverable. | -| Input | Final version of the document(s) (12). | -| Output | Published documentation that is accessible to users. | -| Tools | - Content model
- Documentation publishing platform | +| Description | Add the approved document to the documentation site. Use the content model to define its location and relationship to other content in the table of contents. | +| Goal | Make the documentation organized, discoverable, and connected to related content. | +| Input | Reviewed and approved documentation from Stage 3. | +| Output | Published documentation, integrated into the overall structure. | +| Tools | - Content model
- Documentation publishing platform | + +```mermaid +flowchart LR + subgraph Stage4["Stage 4: Integration & Publication"] + FC["Final content"] --> INT["Integration (Stage 6)"] --> TOC + CM["Content model"] --> INT + + %% Docs site as neutral container holding Table of contents + subgraph DOCSITE["Docs. site"] + TOC["Table of contents"] + end + end + + %% Show link from Stage 3 + STAGE3["Stage 3"] -.-> FC + + classDef main fill:#fff,stroke:#333,stroke-width:2px + classDef support fill:#eef,stroke:#333,stroke-dasharray: 3 3 + classDef stage fill:#fdd,stroke:#c33,stroke-width:2px + classDef container fill:#fff,stroke:#333,stroke-dasharray: 3 3 + + class FC,TOC main + class CM support + class INT stage + class DOCSITE container + class STAGE3 support +``` From 828b4c8866b0bc13b0c234fcf25ffbac7b28058d Mon Sep 17 00:00:00 2001 From: Jorge <62282406+jorge-campo@users.noreply.github.com> Date: Mon, 22 Sep 2025 10:10:42 +0200 Subject: [PATCH 3/3] (#44) content fixes and updates --- .../00-end-to-end-documentation-guide.md | 201 ++++++++++-------- 1 file changed, 107 insertions(+), 94 deletions(-) diff --git a/docs-standards/00-end-to-end-documentation-guide.md b/docs-standards/00-end-to-end-documentation-guide.md index c9ea9b6..de45444 100644 --- a/docs-standards/00-end-to-end-documentation-guide.md +++ b/docs-standards/00-end-to-end-documentation-guide.md @@ -1,165 +1,178 @@ -# End-to-end documentation guide +# IFT technical documentation guide -This guide is for the subject-matter experts (SMEs) who contribute to our products: the developers, infrastructure engineers, and other technical contributors responsible for designing and implementing features. It is written for technical experts who need to produce clear, effective documentation for the solutions they create, but who are not professional technical writers. +This guide is for the subject-matter experts (SMEs) who contribute to [IFT projects](https://free.technology/) ↗ documentation: the developers, infrastructure engineers, and other technical contributors responsible for designing and implementing features. It is written for technical experts who need to produce clear, effective documentation for the solutions they create, but who are not professional technical writers. -Our core assumption is that the primary barrier to writing documentation is not a lack of willingness, but the lack of a clear and repeatable process. This guide provides that process. It is designed to remove ambiguity, eliminate "blank page" anxiety, and provide a predictable workflow to create high-quality documentation consistently. +Our core assumption is that the primary barrier to writing documentation is the lack of a clear and repeatable process. This guide provides that process. It is designed to remove ambiguity, eliminate "blank page" anxiety, and offers a predictable workflow to create high-quality documentation consistently. + +This guide is structured so you can quickly find the process, rules, and resources you need for any documentation task. ## How this guide is organized -This document provides a high-level overview of the documentation workflow, presented as a sequence of four distinct stages: designing the information, populating the content structure, validating the design, and integrating into the overall structure. It is designed to be a map that you can use to navigate the process from an initial idea to a final, published document. +The guide is divided into three main parts: + +- **Stages**: A detailed walkthrough of the four stages of the documentation workflow: design the information, populate the content structure, validate the design, and integrate into the overall structure. +- **Writing rules**: Practical instructions on how to write and format content so it is consistent, clear, and easy to maintain. +- **Annexes**: Reference material such as templates, examples, checklists, and other aids to support you in each stage of the workflow. -This document does not contain exhaustive details. Instead, it functions as a central hub, providing direct links to the specific templates, checklists, writing rules, and external tools required to complete each step of the process. You can use it as a quick reference to find the resources you need for a specific task. +You can read the guide from beginning to end to learn the full process, or jump directly to the section that matches the task at hand. ## The documentation workflow -This guide provides an end-to-end overview of the documentation process, from initial analysis to final integration. Use it to understand each part of the workflow and how they connect. +This section provides an end-to-end overview of the documentation process, from initial analysis to final integration. Use it to understand each part of the workflow and how they connect. -## Stage 1: Designing the information +### Stage 1: Design the information | Element | Description | |:--------|:------------| | Description | Identify the reader’s goal, perform a guided task analysis, and decompose the goal into core information blocks (Concept, Procedure, Reference, Troubleshooting). Organize these blocks into a structural blueprint. | | Goal | Define scope and structure before writing, ensuring alignment with the reader’s goal. | -| Input | Feature code, user stories, and any other existing documentation. | +| Input | Feature code, user stories, design files, and any other existing documentation. | | Output | A content organization plan (blueprint) that specifies what documents are needed and how information will be structured. | -| Tools | - Task analysis template
- Information block organization rules | +| Tools | - Task analysis template
- Information blocks organization rules | ```mermaid flowchart LR - %% Main flow - A[Reader's goal] -->|Task analysis| B((1 Task analysis)) - B --> C[Identify information blocks] - C --> D[Concept] - C --> E[Procedure] - C --> F[Reference] - C --> G[Troubleshooting] - C -->|Organize| H((2 Organize)) - H --> I[Structural blueprint] - - %% Supporting tools - J[Task analysis template] --> B - K[Block organization rules] --> H - - %% Questions - J -.-> JA["A: 'How do I break down the reader's goal?'"] - K -.-> KB["B: 'How do I organize the information?'"] - - %% Styling - style B fill:#fdd,stroke:#333,stroke-width:1px - style H fill:#fdd,stroke:#333,stroke-width:1px - style JA fill:#bbf,stroke:#333,stroke-width:1px - style KB fill:#bbf,stroke:#333,stroke-width:1px + subgraph S1["Stage 1: Designing the information"] + RG([Reader's goal]):::artifact --> TA["Task analysis"]:::action + + %% Information blocks cluster + TA --> IB["Identify information blocks"]:::main + IB --> Cpt["Concept"]:::main + IB --> Proc["Procedure"]:::main + IB --> Ref["Reference"]:::main + IB --> Troub["Troubleshooting"]:::main + + IB --> ORG["Organize"]:::action --> SB([Structural blueprint]):::artifact + + %% Supporting tools (solid links, their own style) + TAT["Task analysis template"]:::tool --> TA + BOR["Block organization rules"]:::tool --> ORG + + %% Questions (dashed links) + Q1["A: 'How do I break down the reader’s goal?'"]:::support -.-> TAT + Q2["B: 'How do I organize the information?'"]:::support -.-> BOR + end + + %% Styles + classDef main fill:#fff,stroke:#333,stroke-width:2px + classDef artifact fill:#FFF7D6,stroke:#333,stroke-width:2px + classDef action fill:#fdd,stroke:#c33,stroke-width:2px + classDef tool fill:#e0ffe0,stroke:#333,stroke-width:2px + classDef support fill:#eef,stroke:#333,stroke-dasharray:3 3 + ``` -## Stage 2: Populating the content structure +### Stage 2: Populate the content structure | Element | Description | |:--------|:------------| | Description | Translate the blueprint into a "good-enough" first draft by filling predefined templates with content drawn from technical sources. Use canonical examples and, where useful, LLMs to assist in generating text. | | Goal | Produce a "good-enough" first draft that matches the designed structure and reduces ambiguity in what needs to be written. | -| Input | Structural blueprint from Stage 1, technical notes, repository content, templates, and examples. | +| Input | Structural blueprint from [Stage 1](#stage-1-design-the-information), technical notes, repository content, templates, and examples. | | Output | A structured "good-enough" draft of the required document(s). | | Tools | - Templates
- Canonical examples
- Writing rules
- Custom prompts for LLM assistance | ```mermaid flowchart LR -%% Stage 2 (Populating the content structure) - -subgraph S1[ ] - direction LR - Stage1[Stage 1]:::stage - SB[Structural blueprint]:::artifact - Stage1 -. from Stage 1 .-> SB -end - -T["Standardized templates"]:::artifact --> CP -W["Writing rules"]:::artifact --> CP -I["Core technical information (notes + repos)"]:::artifact --> CP -X["Canonical examples"]:::artifact --> CP -SB --> CP - -CP[[Custom prompts]]:::prompt --> LLM -LLM[(LLM)]:::process --> GD["Good-enough first draft"]:::output - -%% Styles -classDef artifact fill:#FFF7D6,stroke:#333,stroke-width:1px; %% pale yellow -classDef prompt fill:#E3F2FF,stroke:#333,stroke-width:1px; %% pale blue, distinct shape -classDef process fill:#EFEFEF,stroke:#333,stroke-width:1px; -classDef output fill:#FFFFFF,stroke:#333,stroke-width:1px; -classDef stage fill:#FFFFFF,stroke-dasharray:3 3,stroke:#777; %% dotted outline for Stage 1 box + subgraph Stage2["Stage 2: Populating the content structure"] + SB([Structural blueprint]):::artifact --> CP[Custom prompts]:::action + T["Standardized templates"]:::artifact --> CP + W["Writing rules"]:::tool --> CP + I["Core technical information (notes + repos)"]:::artifact --> CP + X["Canonical examples"]:::artifact --> CP + + CP --> LLM[(LLM)]:::process --> GD([Good-enough first draft]):::artifact + + %% Supporting questions + TQ["C: 'Give me a template I can fill out'"]:::support -.-> T + WQ["D: 'How do I write the content?'"]:::support -.-> W + IQ["E: 'What are my information sources?'"]:::support -.-> I + XQ["F: 'Help me produce a first draft'"]:::support -.-> X + end + + %% Stage 1 shown outside with dashed connection + Stage1["Stage 1"]:::stage -.-> SB + + %% Styles + classDef artifact fill:#FFF7D6,stroke:#333,stroke-width:2px + classDef action fill:#fdd,stroke:#c33,stroke-width:2px + classDef process fill:#EFEFEF,stroke:#333,stroke-width:2px + classDef tool fill:#e0ffe0,stroke:#333,stroke-width:2px + classDef support fill:#eef,stroke:#333,stroke-dasharray:3 3 + classDef stage fill:#fff,stroke:#333,stroke-dasharray:3 3 ``` -## Stage 3: Validating the design +### Stage 3: Validate the design | Element | Description | |:--------|:------------| -| Description | Improve and refine the draft through self-review, applying checklists, writing rules, and linters. Incorporate additional content as needed. Submit the draft in a GitHub pull request, where SMEs review for technical accuracy and confirm that the content effectively supports the user. | +| Description | Improve and refine the draft through self-review, applying checklists, writing rules, and linters. Incorporate additional content as needed. Submit the draft in a GitHub pull request, where SMEs review the content for technical accuracy and confirm that it effectively supports the user. | | Goal | Ensure the documentation is accurate, complete, and structured according to the design. | -| Input | "good-enough" draft from Stage 2. | +| Input | "Good-enough" draft from [Stage 2](#stage-2-populating-the-content-structure). | | Output | Reviewed and refined documentation, technically validated and structurally consistent. | -| Tools | - Review checklists
- Writing rules
- Linters
- GitHub pull request review | +| Tools | - Review checklists
- Writing rules
- Linter
- GitHub pull request review | ```mermaid flowchart LR subgraph Stage3["Stage 3: Review & Refinement"] - GD["Good-enough first draft"] --> SR["Self-review"] --> SD["Second draft"] --> SME["SME review"] --> FC["Final content"] + GD([Good-enough first draft]):::artifact --> SR["Self-review"]:::action --> SD([Second draft]):::artifact --> SME["SME review"]:::action --> FC([Final content]):::artifact %% Supporting tools feeding into Self-review - RC["Review checklist"] --> SR - WR["Writing rules"] --> SR - Lint["Linter"] --> SR + RC["Review checklist"]:::tool --> SR + WR["Writing rules"]:::tool --> SR + Lint["Linter"]:::tool --> SR %% Pull request connected to SME review - PR["Pull request"] -.-> SME + PR["Pull request"]:::tool -.-> SME end %% Dotted line from Stage 2 - Stage2["Stage 2"] -.-> GD + Stage2["Stage 2"]:::stage -.-> GD + %% Styles classDef main fill:#fff,stroke:#333,stroke-width:2px - classDef support fill:#eef,stroke:#333,stroke-dasharray: 3 3 - classDef review fill:#fdd,stroke:#c33,stroke-width:2px - classDef stage fill:#ddd,stroke:#333,stroke-dasharray: 5 5 - - class GD,SD,FC main - class RC,WR,Lint,PR support - class SR,SME review - class Stage2 stage + classDef artifact fill:#FFF7D6,stroke:#333,stroke-width:2px + classDef action fill:#fdd,stroke:#c33,stroke-width:2px + classDef tool fill:#e0ffe0,stroke:#333,stroke-width:2px + classDef support fill:#eef,stroke:#333,stroke-dasharray:3 3 + classDef stage fill:#fff,stroke:#333,stroke-dasharray:3 3 ``` -## Stage 4: Integrating into the overall structure +### Stage 4: Integrate into the overall structure | Element | Description | |:--------|:------------| | Description | Add the approved document to the documentation site. Use the content model to define its location and relationship to other content in the table of contents. | | Goal | Make the documentation organized, discoverable, and connected to related content. | -| Input | Reviewed and approved documentation from Stage 3. | +| Input | Reviewed and approved documentation from [Stage 3](#stage-3-validate-the-design). | | Output | Published documentation, integrated into the overall structure. | | Tools | - Content model
- Documentation publishing platform | ```mermaid flowchart LR - subgraph Stage4["Stage 4: Integration & Publication"] - FC["Final content"] --> INT["Integration (Stage 6)"] --> TOC - CM["Content model"] --> INT + subgraph Stage4["Stage 4: Integration & publication"] + FC([Final content]):::artifact --> INT["Integration"]:::action - %% Docs site as neutral container holding Table of contents - subgraph DOCSITE["Docs. site"] - TOC["Table of contents"] + subgraph DOCSITE["Docs. platform"] + TOC([Table of contents]):::artifact end + + INT --> TOC + CM["Content model"]:::tool --> INT end - %% Show link from Stage 3 - STAGE3["Stage 3"] -.-> FC + S3["Stage 3"]:::stage -.-> FC classDef main fill:#fff,stroke:#333,stroke-width:2px - classDef support fill:#eef,stroke:#333,stroke-dasharray: 3 3 - classDef stage fill:#fdd,stroke:#c33,stroke-width:2px - classDef container fill:#fff,stroke:#333,stroke-dasharray: 3 3 - - class FC,TOC main - class CM support - class INT stage + classDef artifact fill:#FFF7D6,stroke:#333,stroke-width:2px + classDef action fill:#fdd,stroke:#c33,stroke-width:2px + classDef tool fill:#e0ffe0,stroke:#333,stroke-width:2px + classDef support fill:#eef,stroke:#333,stroke-dasharray:3 3 + classDef stage fill:#fff,stroke:#333,stroke-dasharray:3 3 + classDef container fill:#fff,stroke:#333,stroke-dasharray:3 3 + + class FC,TOC artifact + class INT action + class CM tool class DOCSITE container - class STAGE3 support ```