logos-docs/CONTRIBUTING.md

Contributing to Logos documentation

This guide explains how to contribute to the Logos documentation project hosted at logos-docs. It covers the contribution process for anyone - whether you are part of the Logos organization or an external contributor.

Overview

Logos documentation lives in the docs/ folder of this repository. Every document follows one of five canonical templates loosely based on DITA standards, uses a shared set of writing rules, and goes through a review process before publication.

The Docs team (Technical Writers) owns the documentation workflow. R&D teams provide technical input and review. The Red Team validates that published documentation works end-to-end in a testing environment.

Document types

Every document in this project uses one of these types. Choosing the right type is mandatory before writing.

Type	Purpose	Use when...
Quickstart	Get a user from zero to a working result fast.	The reader needs to try something for the first time with minimal setup.
Procedure	Walk through a goal-oriented workflow step by step.	The reader needs to complete a specific task they already understand.
Concept	Explain what something is and how it works.	The reader needs to understand a system, component, or idea before acting.
Reference	Provide structured lookup information.	The reader needs to check a flag, parameter, API field, or config option.
Troubleshooting	Diagnose and fix problems.	The reader hit an error and needs symptom-to-fix guidance.

If you are unsure which type fits, open an issue describing what you want to document and the Docs team will help you choose.

Resources

Resource	Location	Purpose
Canonical templates	resources/templates/	Markdown and JSON templates for each document type. Non-negotiable structure.
Writing rules	resources/writing-rules/	Style guide covering voice, formatting, code blocks, callouts, and terminology.
Doc packet template	resources/templates/doc-packet.md	Template R&D teams use to provide technical input for a new document.
Project board	Logos Docs project board	Tracks every document from intake to publication. Read access is public.
Labels reference	Repository labels	Label taxonomy used on issues and PRs.

How to contribute

Report a problem or request a new document

If you found an error in an existing document, want to request a new document, or have a suggestion, open an issue.

Describe what you need clearly. Include:

• The document path or URL (if reporting a problem with an existing doc).
• What is wrong or missing.
• For new document requests: the user journey or task you want documented, and why it matters.

The Docs team triages issues and decides priority.

Fix or improve an existing document

If you want to fix a typo, clarify a step, update a command, or make any other improvement to an existing document:

1. Fork the repository.
2. Create a branch with a descriptive name (for example, fix/quickstart-node-typo).
3. Make your changes. Follow the writing rules and preserve the existing template structure. Do not reorganize sections or change the document type.
4. Open a pull request against main. In the PR description, explain what you changed and why.
5. The Docs team reviews your PR. For technical changes (commands, config values, expected outputs), an R&D SME may also review.

Keep PRs small and focused. One fix per PR is easier to review than a large batch of unrelated changes.

Write a new document (core contributors)

This section applies to Logos core contributors: R&D engineers, Docs team members, and Red Team members who are part of the full documentation workflow.

Writing a new document follows a phased process tracked on the project board. Each phase has a clear owner and a definition of done.

---

Workflow for core contributors

The documentation process starts with R&D. The SME responsible for a feature or workflow is the one who opens the issue and provides the doc packet. The Docs team then takes that input and turns it into structured, publishable documentation.

Board sections

The project board uses six sections. Each section represents a workflow stage of a document and makes ownership explicit: anyone looking at the board can immediately see whose turn it is to act.

Section	Owner	What happens here	How items enter	How items exit
Backlog	-	Journey is identified but not yet prioritized.	Issue is created.	Docs or Red Team prioritizes and assigns an R&D SME.
Needs input (R&D)	R&D SME	R&D provides the doc packet or a draft in the issue.	Issue is assigned to an SME.	SME posts the doc packet, or 5 business days pass (see time-box rules).
Drafting (Docs)	Docs	Docs writes the document in a PR linked to the issue.	Doc packet received, or input deadline passed.	Draft is ready for review. Review requested on the PR.
In review (R&D + Red Team)	R&D SME + Red Team	SME reviews for technical correctness. Red Team tests end-to-end. Docs incorporates feedback.	PR is marked ready for review.	SME approves and Red Team report passes, or 5 business days pass (see time-box rules).
Final edit (Docs)	Docs	Docs does the editorial pass (structure, grammar, linters) and merges.	Reviews complete or review deadline passed.	PR merged.
Published	-	Document is live on GitHub.	PR is merged.	-

Labels

Labels are organized into four groups. Every issue gets exactly one label from each applicable group.

Area (required, one per issue). Maps to the R&D team responsible for the subject matter.

• area:anoncomms
• area:apps
• area:blockchain
• area:core
• area:lez
• area:messaging
• area:storage

Quality (required, one per issue). Tracks the current quality level of the document. Updated as the document progresses.

Label	Meaning
quality:stub	Placeholder page. Title, status, and known gaps only. Not runnable.
quality:unverified	Structured draft with steps. Not confirmed by an SME.
quality:sme-verified	SME confirmed technical correctness for a specific repo version.
quality:verified	SME confirmed and Red Team tested end-to-end.

Type (required, one per issue).

Label	Meaning
type:journey	A user journey document (the primary deliverable).
type:chore	Repo maintenance, template updates, tooling work.
type:bug	Factual error or broken instructions in a published doc.

Status (required, one per issue). Tracks the current phase in the workflow. See details in Phases in detail.

Blocked-by (optional). Select a blocked-by label when an item cannot progress to indicate the blocker. Write the reason as a comment on the issue. Remove the label when the blocker is resolved.

Release (one per milestone). For example, release:testnet-v0.1, release:testnet-v0.2. Used to filter the GitHub project board by release.

Milestones

Each release has a corresponding GitHub milestone (e.g., "Testnet v0.2"). The milestone groups related issues and provides a progress bar. The milestone due date is the target date for R&D to provide all doc packets for that release.

Issues are added to the milestone when they are prioritized and moved out of Backlog.

Phases in detail

Each journey has a single status:<phase> label and one or more blocked-by:<team> labels — both auto-managed by the Logos Journeys web app based on what's in the issue body. The whole lifecycle is one linear sequence:

flowchart TD
    start([journey created]) --> s1

    subgraph RND[Blocked by R&D]
        s1[confirm-roadmap] --> s2[confirm-date] --> s3[rnd-in-progress]
        s3 -->|date passes| s3o[rnd-overdue]
        s3  --> s4[waiting-for-doc-packet]
        s3o --> s4
    end

    s4 -->|doc-packet link added| s5

    subgraph DOCS[Blocked by Docs]
        s5[doc-packet-delivered]
    end

    s5 -->|doc-PR link added| s6

    subgraph REVIEW[Blocked by R&D SME + Red Team]
        s6[doc-ready-for-review]
    end

    s6 -->|PR merged| s7

    subgraph RT[Blocked by Red Team]
        s7[doc-merged]
    end

    s7 -->|red team tracking closed| fin([completed])

status:*	Next step (who does it)	Blocked by
status:confirm-roadmap	R&D lead: set - team: and a - milestone: URL in the issue body	blocked-by:rnd (or team)
status:confirm-date	R&D lead: add the estimated delivery - date: (DDMmmYY)	blocked-by:rnd-<team>
status:rnd-in-progress	R&D: deliver the roadmap milestones (auto-advances when all are ticked in roadmap.logos.co)	blocked-by:rnd-<team>
status:rnd-overdue	R&D: deliver the milestones — target date has passed, update the date or close them	blocked-by:rnd-<team>
status:waiting-for-doc-packet	R&D: open a doc packet issue, fill it in, paste its URL into ## Doc Packet - link:	blocked-by:rnd-<team>
status:doc-packet-delivered	Docs: open a tracking issue (paste into ## Documentation - tracking:), write the doc, and once the doc PR is ready for review paste its URL into ## Documentation - pr:	blocked-by:docs
status:doc-ready-for-review	R&D and Red Team: review the doc PR. Docs: merge the PR once both have approved	blocked-by:red-team + blocked-by:rnd-<team>
status:doc-merged	Red Team: finish dogfooding, close ## Red Team - tracking: when done	blocked-by:red-team
status:completed	Nothing — journey is done	—

The doc PR URL (## Documentation - pr:) is added manually by the docs team as an explicit "ready for review" signal — there is no auto-discovery.

R&D team granularity: <team> is one of anon-comms, messaging, core, storage, blockchain, zones, smart-contract, devkit.

The hand-offs

1. R&D fills in their team, a roadmap milestone link, and an estimated date. When all milestones are closed (checked against the logos-co/roadmap repo), the phase auto-advances to waiting-for-doc-packet. R&D then opens an issue using the doc packet template, fills it in (including appointing a Subject-Matter Expert from their team), and pastes the issue URL into the - link: field of the ## Doc Packet section. That flip (status:doc-packet-delivered) hands off to Docs.
2. Docs opens a tracking issue in logos-co/logos-docs (pasted into ## Documentation - tracking:) and begins writing. When the doc PR is ready for review, Docs manually pastes the PR URL into ## Documentation - pr: — this is an explicit "ready for review" signal (no auto-discovery), which advances the journey to doc-ready-for-review. Red Team and the R&D SME review on that PR; once approved, Docs merges it → doc-merged.
3. Red Team dogfoods the journey and reviews the doc PR simultaneously. Their tracking issue lives in ## Red Team - tracking:. Closing that issue completes the journey → status:completed. If no red team tracking is provided, the journey is considered complete once the doc PR is merged.

External blockers (blocked-by:legal, blocked-by:security, etc.) can be added manually in the detail panel; they coexist with the lifecycle blocked-by:* labels and don't affect the auto-managed flow.

The app keeps these labels in sync automatically. A ⚠ "Fix Labels" button in the header appears when any issue's labels drift from the computed state; clicking it reconciles everything in one pass (also migrates legacy action:* and blocked:<team> labels).

---

Quality levels

Quality labels track the document's reliability, not its position in the workflow. A document can be published at any quality level. The quality level is visible to readers and sets expectations.

Quality level	What the reader can expect
Stub	The page exists to reserve the journey and show its status. Content is minimal or absent. Not runnable.
Unverified	The document has structured content with steps, but no SME has confirmed correctness. Commands and outputs may be inaccurate.
SME-verified	An R&D SME has confirmed that the technical content is correct for a specific repo version.
Verified	An SME has confirmed correctness and the Red Team has tested the journey end-to-end. This is the highest quality bar.

Document structure rules

All documents must follow these rules regardless of who writes them.

1. Use a canonical template. Every document must use the Markdown template for its type. Templates are in resources/templates/. Do not invent your own structure.
2. Follow the writing rules. The style guide in resources/writing-rules/ defines voice, formatting, terminology, and code block conventions. Read it before writing.
3. One document, one type. Do not mix types. If a quickstart needs a long conceptual explanation, write a separate concept document and link to it.
4. Mark unknowns explicitly. If you do not have the information for a required section, do not skip it. Write a clear note for the reader (for example., "Technical details pending - contact the [team] for status"). Track the gap in the PR or issue.
5. Do not break existing structure. When editing an existing document, preserve its template structure, section IDs, and numbering. Change only what you need to change.