|
| 1 | +--- |
| 2 | +title: "Open Source Documentation" |
| 3 | +sidebar_label: Session Notes |
| 4 | +sidebar_position: 1 |
| 5 | +--- |
| 6 | + |
| 7 | +# Open Source Documentation |
| 8 | + |
| 9 | +This session focuses on contributing to and improving open source documentation in the Cardano ecosystem. Documentation is often the defining factor in an open source project's success or failure, acting as the bridge between the codebase and its users. |
| 10 | + |
| 11 | +## 1. Why Documentation Matters: The Heartbeat of Open Source |
| 12 | + |
| 13 | +Before looking at how to document, it is crucial to understand *why* documentation is the lifeblood of any open source project. |
| 14 | + |
| 15 | +- **Frictionless Onboarding:** The biggest barrier to open source contribution is understanding the codebase. Excellent documentation dramatically lowers the barrier to entry, transforming curious developers into active contributors. |
| 16 | +- **Breaking Down Knowledge Silos:** If only the creator understands how a system works, the project is fragile (a low "bus factor"). Documentation decentralizes knowledge, protecting the project's longevity. |
| 17 | +- **The Ultimate Trust Signal:** Users and enterprises judge the maturity, stability, and reliability of an open source project first by its docs. A poorly documented but brilliantly coded project will almost always lose to a well-documented, average-coded one. |
| 18 | +- **Enabling Asynchronous Collaboration:** Open source spans global time zones. Comprehensive documentation ensures developers aren't blocked waiting 12 hours for a maintainer to wake up and answer a basic question. |
| 19 | + |
| 20 | +### The Cost of Poor Documentation |
| 21 | +Conversely, failing to provide clear, actionable documentation carries severe penalties: |
| 22 | +- **Developer Abandonment:** If a developer cannot set up your project locally within 15 minutes, they will likely abandon it for a competitor's framework. |
| 23 | +- **The Support Burden:** Unclear documentation guarantees that your issue tracker and Discord channels will be flooded with the exact same setup and configuration questions repeatedly, burning out maintainers. |
| 24 | +- **Security by Obscurity (Fails):** "Self-documenting code" is a myth when it comes to system architecture. Without high-level design docs, contributors will unknowingly introduce critical bugs because they lack the zoomed-out context of how different modules interact. |
| 25 | + |
| 26 | +## 2. Documentation Driven Development (DDD) |
| 27 | + |
| 28 | +With the 'why' established, treating documentation as a secondary task is no longer viable. In a **docs-as-code** philosophy, documentation is treated with the same rigor as source code. |
| 29 | + |
| 30 | +- **Start with the docs:** Writing the README, a design doc, or an API specification before writing code clarifies intent, defines API surfaces early, and prevents wasted engineering effort on misunderstood requirements. |
| 31 | +- **Maintain alongside code:** CI pipelines should fail if code changes are not accompanied by the relevant doc updates. Code reviews must include documentation reviews. |
| 32 | + |
| 33 | +## 3. The ROI and Trade-offs of Quality Documentation |
| 34 | + |
| 35 | +While the benefits heavily outweigh the costs, maintaining high-quality documentation is an active investment with real trade-offs. |
| 36 | + |
| 37 | +### The Advantages |
| 38 | +- **Security & Auditing:** This is perhaps the most critical advantage in Web3 and the Cardano ecosystem. Auditors cannot effectively verify if a smart contract securely does what it's supposed to do if there is no documentation defining *what* it is supposed to do. Good specs (like CIPs or formal proofs) drastically reduce audit times and costs. |
| 39 | +- **Scalability of the Team:** With comprehensive documentation, a project can absorb 100 new contributors at once without overwhelming the core maintainers with basic setup questions. |
| 40 | +- **Historical Context (The "Why"):** Code tells you *how* a system works today; documentation (specifically Architecture Decision Records) tells you *why* it was built that way, preventing future developers from repeating old mistakes. |
| 41 | +- **Automated Validation:** When using "Executable Documentation" (tests mapped to requirements), your CI/CD pipeline continuously proves that the documentation reflects reality. |
| 42 | + |
| 43 | +### The "Disadvantages" (Trade-offs) |
| 44 | +- **Maintenance Burden (Documentation Drift):** The worst documentation is *wrong* documentation. Keeping fast-moving code and documentation perfectly synchronized requires significant discipline and often slows down rapid prototyping phases. |
| 45 | +- **High Initial Overhead:** Writing great design docs or mathematical proofs in Typst/LaTeX requires a massive upfront time investment before a single line of application code is written. |
| 46 | +- **The "Wall of Text" Problem:** Over-documenting everything can lead to unreadable, bloated repositories where contributors cannot find the information they actually need. Documentation requires aggressive, thoughtful editing. |
| 47 | + |
| 48 | +## 4. Types of Documentation |
| 49 | + |
| 50 | +A healthy project maintains several layers of documentation: |
| 51 | + |
| 52 | +### The README |
| 53 | +The front door of your project. It must answer: *What is this? How do I install it? How do I use it?* |
| 54 | +- **Essentials:** Badges (build status, version), concise description, quickstart guide, prerequisites, and license. |
| 55 | + |
| 56 | +### Design Docs & Architecture |
| 57 | +Explaining the *why* behind technical decisions, especially for protocol-level changes or major architectural shifts. |
| 58 | +- **Examples:** Cardano Improvement Proposals (CIPs), Architecture Decision Records (ADRs). |
| 59 | + |
| 60 | +### Executable Documentation |
| 61 | +The best documentation is guaranteed to be correct because it is executed. |
| 62 | +- **Unit and Integration Tests:** Show exactly how a component is expected to behave. Test files often serve as the most up-to-date documentation for developers. |
| 63 | + |
| 64 | +### Milestones & Project Management |
| 65 | +Transparent tracking of progress helps contributors know where the project is heading. |
| 66 | +- **Tools:** GitHub/GitLab milestones, issue trackers, and public roadmaps. |
| 67 | + |
| 68 | +### Contributor Guidelines |
| 69 | +A `CONTRIBUTING.md` file explains how others can help, code style conventions, and the pull request process. |
| 70 | + |
| 71 | +## 5. Documentation Formats & Tooling |
| 72 | + |
| 73 | +Different types of documentation require different tools. The format you choose dictates how accessible your documentation is to contributors and how well it integrates with your CI/CD pipelines. |
| 74 | + |
| 75 | +### Markdown (`.md`) |
| 76 | +**Why it matters:** Markdown is the ubiquitous standard for open source. It is lightweight, readable as plain text, and easily version-controlled alongside code. |
| 77 | +**How it's used:** |
| 78 | +- **Primary Use Case:** READMEs, `CONTRIBUTING.md`, changelogs, and general repo documentation. |
| 79 | +- **Tooling:** It is supported natively by GitHub, GitLab, and Bitbucket. For larger projects, Markdown files are compiled into searchable, stylized websites using Static Site Generators (SSGs) like **Docusaurus** (which powers the developer portal you are reading right now!), Sphinx, or MkDocs. |
| 80 | + |
| 81 | +### LaTeX (`.tex`) |
| 82 | +**Why it matters:** LaTeX is the legacy, heavyweight standard for academic publishing and rigorous mathematical documentation. It provides absolute, pixel-perfect control over complex typesetting, formulas, citations, and programmatically drawn diagrams (e.g., via TikZ). |
| 83 | +**How it's used:** |
| 84 | +- **Primary Use Case:** Formal research papers, cryptographic proofs, and foundational protocol whitepapers (e.g., the original Ouroboros papers). |
| 85 | +- **Tooling:** Written in `.tex` files and compiled into PDFs. Its steep learning curve means it is generally reserved for highly specialized research teams rather than general open source contributors. |
| 86 | + |
| 87 | +### Typst (`.typ`) |
| 88 | +**Why it matters:** Typst is a modern, lightning-fast alternative to LaTeX. It features a much cleaner syntax and compiles almost instantly, solving the slow iteration times and complex syntax issues of LaTeX while maintaining robust support for math, multi-page data tables, and integrated diagramming. |
| 89 | +**How it's used:** |
| 90 | +- **Primary Use Case:** Modern whitepapers, technical architecture deep-dives, and math-heavy documentation where authors want professional PDF output without the overhead of learning LaTeX. |
| 91 | +- **Tooling:** Increasingly popular in ecosystems like Cardano and Rust for creating polished technical PDFs straight from a fast, understandable markup language. |
| 92 | + |
| 93 | +### AsciiDoc (`.adoc`) |
| 94 | +*(Pronounced: "ASK-ee-dock", derived from ASCII text)* |
| 95 | +**Why it matters:** If Markdown is a bicycle, AsciiDoc is a tank. AsciiDoc is a highly structured, standardized text format explicitly designed for complex, book-length technical documentation and enterprise publishing. It natively handles advanced elements (like complex tables, footnotes, includes, and warning blocks) that Markdown struggles with. |
| 96 | +**How it's used:** |
| 97 | +- **Primary Use Case:** Enterprise-grade documentation, O'Reilly books, and massive open source projects that outgrow Markdown's simplicity. |
| 98 | +- **Tooling:** Processed using Asciidoctor and often paired with Antora for managing multi-repository documentation sites. |
| 99 | + |
| 100 | +### Mermaid (`.mmd` / Inline) |
| 101 | +**Why it matters:** System architecture and protocol flows are often impossible to explain with text alone, but saving diagrams as static `.png` files means they become instantly outdated when code changes. Mermaid allows you to write diagrams as text. |
| 102 | +**How it's used:** |
| 103 | +- **Primary Use Case:** Rendering sequence diagrams, state charts, and system architecture mapping directly inside Markdown files. |
| 104 | +- **Tooling:** Supported natively by GitHub and Docusaurus. You write text blocks, and the browser dynamically renders them into visual diagrams. |
| 105 | + |
| 106 | +## 6. Modern Tooling: AI & API Specs |
| 107 | + |
| 108 | +Documentation has evolved rapidly. Today, treating docs as code means utilizing modern integrations: |
| 109 | + |
| 110 | +### API Documentation (OpenAPI / Swagger) |
| 111 | +For developers building backend services, indexers, or dApp infrastructure, **OpenAPI schemas** are the absolute gold standard. |
| 112 | +- Rather than manually typing out REST definitions in a README, developers write an OpenAPI YAML/JSON schema. |
| 113 | +- Tools like Swagger UI or Redoc then automatically generate interactive, verifiable documentation sites where users can test endpoints directly from their browser. |
| 114 | + |
| 115 | +### AI Assistants in Documentation |
| 116 | +In 2026, writing the *initial draft* of documentation is increasingly automated. |
| 117 | +- **Generation:** CI/CD pipelines can run LLM-driven reviewers that automatically flag missing docstrings or generate draft PR descriptions based on code diffs. |
| 118 | +- **Translation to Markdown:** Tools like GitHub Copilot can instantly translate complex inline comment blocks into formatted Markdown ready for Docusaurus. The developer's role is shifting from *author* to *editor*. |
| 119 | + |
| 120 | +## 7. Global Open Source: Localization (i18n) |
| 121 | + |
| 122 | +The Cardano community is fiercely global, with massive developer adoption occurring across Africa, India, and Latin America. English-only documentation inherently limits adoption. |
| 123 | + |
| 124 | +- **Internationalization (i18n):** *(Pronounced "eye-eighteen-enn")* This is a standard software numeronym where "18" represents the number of letters between the first 'i' and the last 'n' in the word "internationalization". Documentation must be built with translation in mind from Day 1. |
| 125 | +- **Tooling Support:** Modern Static Site Generators like Docusaurus have built-in i18n support. They allow maintainers to host the exact same documentation structure across multiple language sub-domains (e.g., `es.docs.cardano.org`), enabling global community members to submit PRs translating individual Markdown files. |
| 126 | + |
| 127 | +## 8. Community Insights & Takeaways |
| 128 | + |
| 129 | +During the **Q1 2026 Developer Experience Working Group** session, participants shared several critical real-world insights that go beyond standard tooling guides: |
| 130 | + |
| 131 | +### Human-in-the-loop AI |
| 132 | +- **Bernard Sibanda's Perspective:** AI documentation can often be generic and "abstract." To avoid unhelpful output, maintainers should write 90% of the core documentation manually to ensure the context is correct, then use AI primarily for formatting, grammar correction, and English translation. |
| 133 | +- **Dan Baruka's Tip:** Modern documentation should be built to be "AI-readable" (using tools like API Dog or proper RSS/Markdown structures) to ensure that when developers use LLMs for support, the AI can actually find and interpret the correct, up-to-date data. |
| 134 | + |
| 135 | +### The "Version Drift" Challenge |
| 136 | +- **Israel Chizungu's Experience:** A major blocker for new developers is "outdated documentation" where the version in the docs doesn't match the required library versions. documentation must include clear, high-visibility version indicators to prevent developers from going down rabbit holes with deprecated code. |
| 137 | + |
| 138 | +### The "Middle Layer" Gap |
| 139 | +- **Robertino Martinez's Insight:** There is a significant gap between high-level user guides and low-level generated API docs (like Haddock for Plutus/Haskell). While low-level docs are great for existing contributors, they are "unfriendly" to newcomers. We need a "middle layer" of conceptual documentation that explains *why* and *how* different modules (like addresses or credentials) interact before dumping developers into the raw API. |
| 140 | + |
| 141 | +### The Case for Centralization |
| 142 | +- **The Scrappy vs. Scale Problem:** Documentation is currently scattered across various organizations (CF, IOG, Intersect). The community consensus is a strong desire for a **centralized entry point** (like `cardano.org` or `developers.cardano.org`) that acts as the "front door" to the entire ecosystem's documentation. |
| 143 | + |
| 144 | +--- |
| 145 | + |
| 146 | +For a curated list of best-in-class repositories and deep-dive learning resources for Markdown, AsciiDoc, LaTeX, and Typst, see our [Full Resources List](../session-resources/readme.md). |
| 147 | + |
| 148 | +--- |
| 149 | + |
| 150 | +*This session is part of the Q1 2026 Developer Experience Working Group: "Laying the Foundations"* |
0 commit comments