YNU-829: Add Repository Documentation Guidelines#617
Conversation
Co-authored-by: Anton Filonenko <philanton@users.noreply.github.com>
dimast-x
requested review from
alessio,
ihsraham,
nksazonov and
philanton
as code owners
dimast-x
changed the title
📝 WalkthroughWalkthroughA new documentation guide file has been added establishing standardized documentation practices for the repository. It defines structure, terminology management, content requirements, and formatting rules across protocol, system architecture, build, and operator documentation domains. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (9)
docs/guide.md (9)
240-250: Fix heading hierarchy for proper document structure.Lines 240 and 247 use h3 (
###) headings directly under an h1 (#) heading, violating the incremental heading hierarchy. Headings should increment by one level at a time (h1 → h2 → h3). This affects both document structure and navigation.🔧 Proposed fix for heading levels
-### Protocol answers +## Protocol answersWhat are the rules of the system?
-### Architecture answers +## Architecture answersHow does Nitrolite implement those rules?
</details> As per coding guidelines, markdownlint rule MD001 requires heading levels to increment by one level at a time. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/guide.mdaround lines 240 - 250, The headings "Protocol answers" and
"Architecture answers" are using h3 (###) directly under the document's h1 which
violates incremental heading hierarchy; update those headings to h2 (##) so they
increment properly (h1 → h2 → h3) — specifically change the "Protocol answers"
and "Architecture answers" headings from ### to ## to satisfy markdownlint MD001
and restore correct document structure.</details> --- `393-403`: **Fix heading hierarchy for writing requirements.** Lines 393, 397, and 401 use h3 (`###`) headings directly under an h1 (`#`) heading, violating the incremental heading hierarchy rule. This is particularly important in a section defining writing requirements, as the document should exemplify the standards it prescribes. <details> <summary>🔧 Proposed fix for heading levels</summary> ```diff -### Use precise terminology +## Use precise terminology Always use defined protocol terms. -### Avoid ambiguity +## Avoid ambiguity Explain behaviour explicitly. -### Avoid implementation leakage in protocol docs +## Avoid implementation leakage in protocol docs Protocol documentation must not reference code.As per coding guidelines, markdownlint rule MD001 requires heading levels to increment by one level at a time.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guide.md` around lines 393 - 403, The three headings "Use precise terminology", "Avoid ambiguity", and "Avoid implementation leakage in protocol docs" are using h3 (###) directly under an h1 and should be incremented one level; change those headings to h2 (##) so the hierarchy increments properly (e.g., adjust the headings for the functions/sections titled "Use precise terminology", "Avoid ambiguity", and "Avoid implementation leakage in protocol docs" from ### to ##).
93-95: Add language specifiers to fenced code blocks.Multiple fenced code blocks throughout the protocol documentation sections are missing language specifications, flagged by markdownlint (MD040). Adding appropriate specifiers improves rendering consistency.
🔧 Proposed fixes for multiple blocks
For the path specification at lines 93-95:
-``` +```text docs/protocol/terminology.mdFor the terminology example at lines 118-133: ```diff -``` +```markdown ## Channel DefinitionFor paths at lines 147-149:
-``` +```text docs/protocol/For the file list at lines 153-158: ```diff -``` +```text overview.md terminology.mdAs per coding guidelines, markdownlint rule MD040 recommends specifying a language for all fenced code blocks.
Also applies to: 118-133, 147-158
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guide.md` around lines 93 - 95, Several fenced code blocks in the protocol docs lack language specifiers (MD040); update each fenced block referenced—specifically the block containing "docs/protocol/terminology.md", the block that begins with "## Channel" (terminology example), the block containing "docs/protocol/", and the block listing "overview.md" / "terminology.md"—by adding appropriate language specifiers (e.g., use ```text for file/path listings and ```markdown for markdown fragments) so markdownlint passes and rendering is consistent.
347-359: Add language specifiers to template code blocks.The template examples for README and Overview documents are missing language specifications, flagged by markdownlint (MD040). Since these are markdown templates, specifying
markdownwould be most appropriate.🔧 Proposed fixes
For README template at lines 347-359:
-``` +```markdown # Project Name Short description of the project.For Overview template at lines 367-385:
-``` +```markdown # Overview ## PurposeAs per coding guidelines, markdownlint rule MD040 recommends specifying a language for all fenced code blocks.
Also applies to: 367-385
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guide.md` around lines 347 - 359, Update the fenced code blocks in the markdown templates so they include the language specifier "markdown": modify the code block that begins with "# Project Name" (the README template) and the one that begins with "# Overview" (the Overview template) to use triple backticks followed by "markdown" (```markdown) to satisfy MD040; ensure any other fenced blocks in the same sections (lines around those headings) are updated similarly.
287-296: Fix list structure and numbering.The numbered list structure is inconsistent. Item "1." at line 287 is followed by items "2." and "3." at lines 294-295, but they appear to be at the same level rather than being part of a continuous numbered list. This creates ambiguity about the document structure.
📋 Proposed fix for list structure
Either format as a continuous numbered list:
+Recommended content structure: + 1. **app.md** must cover: * how to register an app * app session lifecycle * concept of daily allowances * app session keys 2. **develop.md** must list SDK methods necessary for app development. + 3. **examples.md** must show real-world use case examples of application flows built with the SDK. Starting with simplest examples and gradually increasing complexity.Or if these are separate sections, use h2/h3 headings instead of numbers:
-1. **app.md** must cover: +## app.md + +This document must cover:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guide.md` around lines 287 - 296, The numbered list in docs/guide.md is malformed: the block starting with "1. **app.md** must cover:" and the subsequent "2." and "3." entries are inconsistent; fix by making it a single continuous numbered list (ensure "1.", "2.", "3." are at the same indentation level and each list item contains the subbullets for app.md) or convert each top-level item into a proper section heading (e.g., "## app.md", "## develop.md", "## examples.md") and move the subpoints (how to register an app, app session lifecycle, concept of daily allowances, app session keys) under the app.md section; update list/heading formatting so app.md, develop.md, and examples.md are clearly distinct items and rendering is consistent.
74-81: Add language specifier to fenced code block.The markdownlint tool flags this code block for missing a language specification. While the directory structure renders fine without it, adding a language identifier improves consistency and explicit rendering behavior.
🔧 Proposed fix
-``` +```text docs/ protocol/As per coding guidelines, markdownlint rule MD040 recommends specifying a language for all fenced code blocks.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guide.md` around lines 74 - 81, The fenced code block containing the directory list (the triple backticks surrounding the lines "docs/", "protocol/", "architecture/", "build/", "operator/") is missing a language specifier; update the opening fence from ``` to ```text so the block becomes a text‑fenced code block and satisfies markdownlint MD040 (i.e., change the initial ``` to ```text for the directory listing code fence).
29-35: Consider shortening the table entry for consistency.The entry "Build Apps on Yellow Network" in the table is notably longer than the other entries ("Protocol definitions", "System architecture", "Operator instructions"). For consistency and scannability, consider shortening to "Build documentation" or "Build guides" to match the concise style of other entries.
📝 Proposed change for consistency
| Information | Canonical location | | --------------------- | ------------------------------ | | Protocol definitions | `docs/protocol/terminology.md` | | System architecture | `docs/architecture/` | -| Build Apps on Yellow Network | `docs/build/` | +| Build documentation | `docs/build/` | | Operator instructions | `docs/operator/` | | Code behaviour | Go code comments |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guide.md` around lines 29 - 35, Replace the long table cell text "Build Apps on Yellow Network" in the Markdown table headed by "Information | Canonical location" with a shorter, consistent label such as "Build documentation" or "Build guides" (update the row where that phrase appears) so the entry matches the concise style of the other items like "Protocol definitions" and "System architecture".
272-283: Add language specifiers to fenced code blocks.Code blocks in the Build and Operator sections are missing language specifications, flagged by markdownlint (MD040).
🔧 Proposed fixes
For paths at lines 272-274:
-``` +```text docs/build/For file lists at lines 278-283: ```diff -``` +```text overview.md app.mdFor paths at lines 306-308:
-``` +```text docs/operator/For file lists at lines 312-317: ```diff -``` +```text running-node.md configuration.mdAs per coding guidelines, markdownlint rule MD040 recommends specifying a language for all fenced code blocks.
Also applies to: 306-317
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guide.md` around lines 272 - 283, Add explicit language specifiers (e.g., "text") to the fenced code blocks that list paths and file names so markdownlint MD040 is satisfied; update the fenced blocks containing "docs/build/", the file lists that include "overview.md", "app.md", "develop.md", "examples.md", the block containing "docs/operator/", and the file lists with "running-node.md" and "configuration.md" to use a language tag (for example changing ``` to ```text) while preserving the exact contents of those blocks.
201-213: Add language specifiers to fenced code blocks.Several code blocks in the architecture section are missing language specifications, flagged by markdownlint (MD040).
🔧 Proposed fixes
For the path at lines 201-203:
-``` +```text docs/architecture/For the file list at lines 207-213: ```diff -``` +```text system-overview.md node-architecture.mdFor the question blocks at lines 242-244 and 248-250:
-``` +```text What are the rules of the system?```diff -``` +```text How does Nitrolite implement those rules?</details> As per coding guidelines, markdownlint rule MD040 recommends specifying a language for all fenced code blocks. Also applies to: 242-244, 248-250 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/guide.mdaround lines 201 - 213, Add explicit language specifiers (use
"text") to the fenced code blocks that currently have no language: the block
containing "docs/architecture/", the block listing "system-overview.md",
"node-architecture.md", "storage.md", "networking.md", "security.md", and the
question blocks containing "What are the rules of the system?" and "How does
Nitrolite implement those rules?"; update each openingtotext so
markdownlint MD040 is satisfied.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In@docs/guide.md:
- Around line 240-250: The headings "Protocol answers" and "Architecture
answers" are using h3 (###) directly under the document's h1 which violates
incremental heading hierarchy; update those headings to h2 (##) so they
increment properly (h1 → h2 → h3) — specifically change the "Protocol answers"
and "Architecture answers" headings from ### to ## to satisfy markdownlint MD001
and restore correct document structure.- Around line 393-403: The three headings "Use precise terminology", "Avoid
ambiguity", and "Avoid implementation leakage in protocol docs" are using h3
(###) directly under an h1 and should be incremented one level; change those
headings to h2 (##) so the hierarchy increments properly (e.g., adjust the
headings for the functions/sections titled "Use precise terminology", "Avoid
ambiguity", and "Avoid implementation leakage in protocol docs" from ### to ##).- Around line 93-95: Several fenced code blocks in the protocol docs lack
language specifiers (MD040); update each fenced block referenced—specifically
the block containing "docs/protocol/terminology.md", the block that begins with
"## Channel" (terminology example), the block containing "docs/protocol/", and
the block listing "overview.md" / "terminology.md"—by adding appropriate
language specifiers (e.g., usetext for file/path listings andmarkdown
for markdown fragments) so markdownlint passes and rendering is consistent.- Around line 347-359: Update the fenced code blocks in the markdown templates
so they include the language specifier "markdown": modify the code block that
begins with "# Project Name" (the README template) and the one that begins with
"# Overview" (the Overview template) to use triple backticks followed by
"markdown" (```markdown) to satisfy MD040; ensure any other fenced blocks in the
same sections (lines around those headings) are updated similarly.- Around line 287-296: The numbered list in docs/guide.md is malformed: the
block starting with "1. app.md must cover:" and the subsequent "2." and "3."
entries are inconsistent; fix by making it a single continuous numbered list
(ensure "1.", "2.", "3." are at the same indentation level and each list item
contains the subbullets for app.md) or convert each top-level item into a proper
section heading (e.g., "## app.md", "## develop.md", "## examples.md") and move
the subpoints (how to register an app, app session lifecycle, concept of daily
allowances, app session keys) under the app.md section; update list/heading
formatting so app.md, develop.md, and examples.md are clearly distinct items and
rendering is consistent.- Around line 74-81: The fenced code block containing the directory list (the
triple backticks surrounding the lines "docs/", "protocol/", "architecture/",
"build/", "operator/") is missing a language specifier; update the opening fence
fromtotext so the block becomes a text‑fenced code block and satisfies
markdownlint MD040 (i.e., change the initialtotext for the directory
listing code fence).- Around line 29-35: Replace the long table cell text "Build Apps on Yellow
Network" in the Markdown table headed by "Information | Canonical location" with
a shorter, consistent label such as "Build documentation" or "Build guides"
(update the row where that phrase appears) so the entry matches the concise
style of the other items like "Protocol definitions" and "System architecture".- Around line 272-283: Add explicit language specifiers (e.g., "text") to the
fenced code blocks that list paths and file names so markdownlint MD040 is
satisfied; update the fenced blocks containing "docs/build/", the file lists
that include "overview.md", "app.md", "develop.md", "examples.md", the block
containing "docs/operator/", and the file lists with "running-node.md" and
"configuration.md" to use a language tag (for example changingtotext)
while preserving the exact contents of those blocks.- Around line 201-213: Add explicit language specifiers (use "text") to the
fenced code blocks that currently have no language: the block containing
"docs/architecture/", the block listing "system-overview.md",
"node-architecture.md", "storage.md", "networking.md", "security.md", and the
question blocks containing "What are the rules of the system?" and "How does
Nitrolite implement those rules?"; update each openingtotext so
markdownlint MD040 is satisfied.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro **Run ID**: `41dde8c9-33ec-40b1-b3d7-9265af0004fc` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 668ab4981dfc70c0e11f284f1ce00eec11d3b2c1 and 66c323ec851db4930ad01a780198a4bfb7742bbb. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `docs/guide.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
nksazonov
left a comment
nksazonov
left a comment
There was a problem hiding this comment.
Overall, a great PR! Some nitpicks, as always 😉
| @@ -0,0 +1,403 @@ | |||
| # Nitrolite Documentation Guide | |||
|
|
|||
| This document defines **how documentation should be written and structured** inside the Nitrolite repositories. | |||
There was a problem hiding this comment.
Here you specify "repositories" (plural), but the first point in purposes specifies "repository" (singular). This creates a confusion.
| * avoids duplication | ||
| * focuses on the most important information first | ||
|
|
||
| This guide must be followed when writing any documentation for the Nitrolite project. |
There was a problem hiding this comment.
I have never heard a "Nitrolite project" term. We should agree on something in between "Nitrolite protocol implementation", "Nitrolite protocol"...
|
|
||
| 1. Protocol | ||
| 2. System Architecture | ||
| 3. Build |
There was a problem hiding this comment.
| 3. Build | |
| 3. Build (as in "build your applications on Yellow Network") |
There was a problem hiding this comment.
And generally, it would be good to clarify in a sentence what each domain is about (even considering there are whole sections about them later)
| ``` | ||
| docs/ | ||
|
|
||
| protocol/ | ||
| architecture/ | ||
| build/ | ||
| operator/ | ||
| ``` |
There was a problem hiding this comment.
I think 4 domains directories were intended to be inside docs/, however here it is not the case.
|
|
||
| Protocol documentation must remain **implementation-independent**. | ||
|
|
||
| Architecture documentation describes **Nitrolite specifically**. |
There was a problem hiding this comment.
Isn't "Nitrolite" a name of the protocol, whereas "Clearnode" / "Clearnet" - the name of the implementation?
|
|
||
| --- | ||
|
|
||
| # 7. Build Apps on Yellow Network Documentation |
There was a problem hiding this comment.
| # 7. Build Apps on Yellow Network Documentation | |
| # 7. "Build Apps on Yellow Network" Documentation |
3 participants
Summary by CodeRabbit