标签：#document

The choice is usually made by whoever draws the first diagram, and then everybody lives with it for years. It is worth five minutes of thought, and the deciding question is not which tool is best but who will edit this thing next. Short answer. A visual editor such as draw.io for diagrams that non-engineers maintain. Mermaid or PlantUML when the diagram belongs with the code and should be reviewed like code. An attached SVG when the picture comes from a design tool and you need it to look exactly right. A screenshot when the diagram will genuinely never change again. The four options A diagramming app inside Confluence draw.io is the common choice, and it is free for small teams. The diagram is created and edited inside the page, links on shapes work, and anyone who can use a mouse can maintain it. This is the default answer for architecture maps, process flows and floor plans that live in the documentation and get corrected by whoever notices the mistake. The cost is lock-in of a mild kind: the diagram lives in the app's format, and moving to something else later means exporting and redrawing. Mermaid or PlantUML: diagrams as text Here the diagram is source code — a few lines describing nodes and arrows, rendered into a picture. The appeal is real: text goes into version control, diffs are readable, and a diagram can be generated by a script from the system it describes. Two things to know before choosing this. Confluence Cloud does not render Mermaid natively, so you need an app for it, and several of them exist including free ones. And the editing audience narrows sharply: a technical writer will not touch a diagram that has to be edited as syntax, so the diagram becomes the property of the engineers, whether you intended that or not. An SVG made somewhere else The diagram comes from Figma, Illustrator, Inkscape, Visio or an architecture tool, and lands on the page as an attachment. It looks exactly as designed, which is why people do it. The catch is documented

Blume is an open-source documentation framework that converts Markdown into a complete documentation site. Built with Astro and Vite, it requires only Node.js and a single Markdown file for setup. The framework supports various configurations, offers automatic SEO features, and includes tools for document testing. It facilitates migration from other documentation systems. By Daniel Curtis

Last week I deleted a function that had been "documented" by a comment explaining a behavior the function hadn't had in three versions. The comment was confident. The function was gone. This is the real failure mode of AI-generated docs: they can be fluent, plausible, and wrong. Not because the model is bad, but because no human verified what the text claims. The fix isn't to avoid AI. It's to build a checkpoint where the model drafts and the human signs off. The Ownership Split A model can summarize code, describe parameters, and turn commit messages into release notes. It cannot know why a decision was made, which edge cases are career-ending, or which comments are now dangerous. My rule of thumb: The model drafts: API descriptions, usage examples, parameter tables, changelog bullets from git history. A human owns: security implications, business rules, architectural trade-offs, deprecation warnings, anything tied to customer promises. The pipeline below makes that split explicit. It generates a draft, then forces a review issue with a checklist that separates the two categories. The Pipeline I run this as a GitHub Actions workflow on every merged PR that touches src/ . It takes the diff, sends it to a language model with a strict output schema, and opens a documentation review issue. Here's a condensed version of the workflow YAML: name : docs-draft on : pull_request : types : [ closed ] branches : [ main ] jobs : draft : runs-on : ubuntu-latest steps : - uses : actions/checkout@v4 with : fetch-depth : 0 - name : Generate doc draft env : API_BASE : ${{ secrets.MONKEYCODE_API_BASE }} API_KEY : ${{ secrets.MONKEYCODE_API_KEY }} run : | git diff origin/main HEAD -- src/ > diff.txt python draft_docs.py diff.txt - name : Open review issue uses : actions/github-script@v7 with : script : | const body = require('fs').readFileSync('review_body.md', 'utf8') await github.rest.issues.create({ owner: context.repo.owner, repo: context.repo.repo, title: `Docs review: ${context.

How It Started I am a backend software engineer, primarily working in the Java ecosystem. Most developers in my space know about PlantUML and have probably been using it for years—I certainly have. PlantUML has long been a go-to tool for developers who need a robust way to write UML diagrams as code. But let's face it: PlantUML is showing its age. As powerful as it is, PlantUML can feel slow, its default look-and-feel is dated, and its interactive feature set has lagged behind modern development workflows. That is a major reason why alternatives have gained so much ground. Tools like Draw.io and Mermaid.js have steadily captured a large portion of the mindshare that PlantUML once held. While Draw.io is a visual drag-and-drop tool rather than a pure text DSL, it offers rich component sets and high customizability. However, text-based versioning and quick code playback aren't its primary strengths. On the other hand, Mermaid.js brought text-to-diagramming into the modern web. It is fast, renders across browsers and IDEs, offers an accessible DSL, and integrates directly into platforms like GitHub and Notion. Yet, I felt we could take this concept even further. We need something more modern, more customizable, and more tactile—a text-to-diagram engine that is fast, easy to learn, and visually sharp, while bridging the gap between raw code and visual canvas control. Introducing DrakoFlow For a long time, I’ve dreamed of having a diagram engine that makes sharing architecture effortless. A tool that enhances the documentation experience rather than standing in the way of it. So, I finally decided to build it. I wanted DrakoFlow to be fast, robust, and elegant—not only in its syntax, but in its visual output. Most importantly, I wanted it to be 100% free, open-source, and privacy-first (running entirely in the browser with zero server dependencies). Building it was a challenge. As a backend developer, creating a heavily interactive, client-side web application meant stepp

The most common documentation failure is not a weak prompt or a lazy writer; it is the absence of a clear boundary between machine-draftable content and human-owned claims. A pipeline that drafts reference sections with free-tier model access and then verifies them with a symbol drift check turns docs into a testable artifact instead of a trust exercise. The model writes the inventory, and the human owns the promises. Why documentation rots inside a healthy CI pipeline Documentation bugs share a distinctive property: they are usually discovered by the people who consume the API, not by the pipeline that builds it. A function renamed in the last refactor stays documented under its old name until a user files an issue, and a newly added flag never appears in the docs at all. The root cause is structural, because nothing in the merge pipeline compares the documented surface against the actual code surface. A prompt cannot know what changed inside a pull request, so the fix has to live in the pipeline around the model. The workflow drafts reference material, validates that every documented symbol still exists, and routes the remaining claims to a human reviewer. That division of labor is the entire design, and each step has a concrete tool. The ownership boundary: what a model may draft The first step is to separate documentation into two classes by asking a single question: can this statement be verified against the codebase alone? If the answer is yes, a model may draft it, and if the answer is no, a human must own it. The table below applies that test to the statement types that appear in most API docs. The model may draft A human must own Function and class inventories Behavioral guarantees CLI flags and their defaults Security and authentication properties Config keys and their types Compatibility and support promises Error codes and exit statuses Deprecation timelines Compilable usage examples Performance or cost claims Parameter descriptions from signatures Ratio

In release 4.0, the Ruby Powers-That-Be have brought class Pathname into the Ruby core. This is a Very Good Thing. Through its many instance methods, a Pathname object provides a consistent and convenient interface to numerous methods in other classes and modules: Wraps almost all methods in class File and module FileTest . Wraps some methods in class Dir and module FileUtils . Advantages of using Pathname instead of these others: You don’t have to know which class or module has which methods. You don’t have to keep typing the class name and path variable. However, for many of the Pathname methods, the existing documentation merely links to another method in another class, with scant or no local examples. That documentation may be seen in Ruby 4.0 . I've completed a re-write of the documentation (with the usual excellent reviewing by Peter Zhu). It may be seen for now in Ruby master , and which will be release with Ruby 4.1 later this year. The re-write gives a Pathname -local description and example for each method. (No more linking to a similar or underlying method elsewhere.) I've also revised the documentation for the class itself, and added a "What's Here" section. Happy Pathnames!

Every developer has been there: you clone a promising repository, and the README is either missing, three years stale, or says "docs coming soon." Even when documentation exists, you still have to wade through thousands of lines of code to understand the architecture, entry points, and dependencies. grow-hack is an open-source project that aims to eliminate that pain. Paste a public GitHub URL, wait about sixty seconds, and receive a complete, professional documentation package — Markdown and styled PDF — generated by an LLM that actually reads the code, not just the README. This is the first module of a larger content creation platform. The core idea is that once a repository is parsed and analyzed, the resulting RepositoryKnowledge object becomes a reusable asset for future modules: blog posts, LinkedIn articles, X threads, tutorials, and presentations. In this teardown, we'll look at how grow-hack works, the smart engineering choices it makes, and why it's more than just a documentation generator. The Pipeline: From URL to PDF The application is a Flask web app that orchestrates a LangGraph-based agent pipeline. The flow is straightforward: Flask UI -> LangGraph workflow -> GitHub fetch -> Parser -> Analyzer -> Knowledge object -> Documentation generator -> Reviewer -> Markdown/PDF Each stage is handled by a dedicated agent: GitHub Agent ( agents/github_agent.py ): Validates the URL, fetches metadata via the GitHub REST API (using PyGithub), and clones the repository with GitPython. Parser ( services/parser.py ): The workhorse. It walks the repository tree, ignoring generated directories and binary files, and extracts README, configuration files, dependencies, and source code structure. It infers the language, framework, package manager, entry points, and overall architecture. Analysis Agent ( agents/analysis_agent.py ): Takes the parsed data and, with the help of an LLM, produces a structured RepositoryKnowledge object. Documentation Agent ( agents/documentation

Disclosure: I build Schemity , a desktop ERD tool - this post is from our blog and uses it for the examples. TL;DR: The database has a built-in place to document a column - COMMENT ON COLUMN in PostgreSQL, the COMMENT attribute in MySQL - and almost nobody fills it in, because a sentence of prose has to travel the same path as a schema change: a migration file, a review, a deploy. Schemity keeps field descriptions in the diagram instead, where editing one generates no SQL, reads existing database comments in on import, and exports the result as a data dictionary. You can document a database column without touching the database: write the description in the model rather than in the schema. That sounds like a dodge until you price the alternative. The database's own mechanism for column documentation, COMMENT ON COLUMN in PostgreSQL and the COMMENT attribute in MySQL, sends a sentence of prose down exactly the same path as a change to how data is stored - a migration file, a code review, an approval, a deploy window - and on MySQL it does something worse than that. Schemity keeps field descriptions in the diagram, where editing one produces no SQL at all. This is why so many production schemas have thousands of columns and almost no comments. Not because nobody wanted to write them. Because writing one costs a deploy. How do I document a database column without running a migration? Keep the description in the model rather than in the storage engine. A field description is a fact about what the column means to your team; it changes no type, no constraint, no index, and nothing about what the database will accept. When it lives in the diagram, editing it is like editing a comment in a code file: you change it, review it in the same pull request as everything else, and nothing has to run against production for it to take effect. The moment that description is a column comment, it stops being prose and becomes DDL. Now it needs a migration file, and the migration needs a

Survivors reconnect with those who saved them in National Geographic's 9/11: Reunited .

Originally published on hexisteme notes . I keep my operating judgment in small, versioned files — one file per decision, each with a status, a list of what it supersedes, and a change history. It's a lightweight way to stop re-litigating the same argument every few weeks: write the judgment down once, and the next time the situation comes up, read the file instead of re-deriving the answer from scratch. Most of the time this works exactly as intended — a rule gets written, a rule gets proven wrong, a newer rule replaces it, done. This is the story of the one time that didn't happen, and why "didn't happen" doesn't look like an error. It looks like a rule sitting there, marked active, doing precisely what it was told to do. The gate One of my rules governed how to use a panel of eight simulated reviewers I sometimes convene for open-ended judgment calls — different personas critiquing the same plan from different angles. The panel's response includes, among other things, an "internal consistency" score: roughly, how much the eight answers agree with each other. Early on I wrote a gate around that number: if internal consistency comes back under 70%, don't adopt the panel's conclusion on its own. Low agreement, the reasoning went, meant the panel hadn't converged on anything trustworthy. The supersession, with receipts The gate lasted exactly as long as it took to hit a counterexample. I ran the panel on an architecture question and got back a response at 21% internal consistency — a reject, by the gate's own arithmetic. Except when I actually read the eight answers instead of just their agreement score, three of them were pointing at things I hadn't considered at all: a missing measurement step behind a database-performance claim, a conflation of a plan's stated purpose with its surface description, and one persona's terse near-empty answer that turned out to be a legitimate signal — a comment that the question itself wasn't well-formed for consensus, not a dodge. A

A new Apple documentary explores the life of Aziz “Zyzz” Shavershian, who rocketed to internet fame in an age before influencers, then died at age 22 in 2011.

On 1 August I opened an issue that was three sentences long. A hundred and one minutes later the feature was merged, and the document that got it there ran to 457 lines . I didn't write those 457 lines. In fact, I didn't have to write any more documentation, and not because I simply allowed Claude to run amok. Here is the issue in full — control-api#265 , 225 characters: control-api#265 — Manifest-backed dashboard feeds For each dashboard, auto create a manifest keyed by dashboard_id. For each sensor the dashboard uses, tag it to be included in the manifest. When a dashboard definition is updated, add / remove tags from sensors accordingly. From that genesis moment, this is the lifecycle of the issue all the way through to landing: Time (UTC) Event 14:25 Issue #265 opened — 225 characters 14:54 FEAT-0007 spec committed — 457 lines 15:35 Spec merged (PR #266) 15:51 Implementation committed 16:06 Implementation merged (PR #267, 15 files), issue closed The interesting part isn't the speed. It's the step at 14:54 that landed a previously non-existent spec document, and what happened in the twenty-nine minutes before it. The issue was never a specification I often write issues like this one...the way most people write shopping lists. Actuator address is not ensured? Baseline the trace correctly. With the pre-rolls, the frame-rate looks out. They're abbreviated to the point of being cryptic to everyone else. I write them this way deliberately: I'm usually mid-something else when I notice a problem, or have an idea for a better route to the solution. The cost of a full write-up right at that moment would be a fractured sense of flow. As most engineers will tell you, the transitions into and out of flow are the most disruptive parts of their working day. This terse form of issue-writing can be all you need, and it's worth being precise about why it works and the trade-offs it includes. It is not because "the issues are good enough". They aren't. When you pick one of these u

Introduction: The Debate Over Code Comments In the trenches of software development, a quiet but fierce debate rages: are code comments still relevant? On one side, the prevailing narrative dismisses comments as "mostly useless" —redundant, outdated, or worse, misleading. This perspective has gained traction, fueled by the rise of self-documenting practices like meaningful variable names and modular design. Developers, under the gun of tight deadlines, increasingly treat comments as an afterthought, if not a burden. The result? Comments are neglected, both in writing and reading, creating a self-fulfilling prophecy of their uselessness. But here’s the rub: this dismissive attitude is flawed. When used thoughtfully, comments are not just useful—they’re critical. The problem isn’t comments themselves but how they’re misused or ignored. Poorly written comments, lack of maintenance standards, and time constraints have deformed their purpose, turning a powerful tool into a liability. For example, a stale comment explaining a function’s behavior can lead a developer to misinterpret the code, causing bugs that cascade through the system. The mechanism here is clear: impact (misleading comment) -> internal process (developer misinterprets code) -> observable effect (bugs introduced) . The stakes are high. As software complexity grows and developer turnover accelerates, the need for clear, maintainable code becomes non-negotiable. Comments, when crafted with intent, act as a bridge between the code’s logic and the human mind, reducing cognitive load and fostering collaboration. Neglecting them risks eroding code readability, maintainability, and team productivity—a risk that materializes when a new developer inherits a poorly documented codebase and spends hours deciphering its intent. This investigation challenges the dismissive attitude toward comments, dissecting their underappreciated utility through real-world examples. By addressing misconceptions and promoting best pr

Originally published at https://ninadpathak.com/articles/technical-documentation-template/ . Creating documentation often forces several decisions at once: where readers begin, how they complete the first task, where exact details belong, and how they recover when a step fails. A template reduces that first pass to a structure you can inspect and adapt. I built this template to solve a narrow problem: an empty documentation repository leaves every contributor to invent navigation, page responsibilities, and release checks again. It provides five focused pages, a local validator, and a strict build path so the structure is useful before the product-specific writing begins. Download the technical documentation template Download the template Unpack the archive, then replace the placeholders with evidence from your product. The remaining sections show what belongs in each page and how to verify the result. What a technical documentation template should include A technical documentation template is a reusable starting structure for product or engineering documentation. It should tell a contributor where a reader begins, where they complete a task, where they look up stable details, and where they recover from a known failure. A table of contents alone cannot do that work. It can label a page “Getting started” without establishing prerequisites, a tested command, an expected result, or a recovery path. The starter contains five pages because they create a complete first route without pretending every product needs the same collection. Page Reader job Evidence to add before publishing index.md Choose the first useful task A direct route to the right starting page getting-started.md Complete first setup Prerequisites, a tested command, expected output guides/send-a-request.md Perform one bounded task A full request and response or observable state reference/configuration.md Look up stable details Names, types, defaults, and constraints troubleshooting.md Recover from a know

A pattern I’ve seen many times in software projects is that documentation starts too late and documents the wrong thing. A team ships a feature, the code works, the tests pass, and everyone moves on. Maybe someone adds a README section, maybe not. If they do, it usually explains how to run something, how to call an endpoint, or what a component does. That kind of documentation is useful, but it often misses the part future developers need most. It misses the decision. Six months later, someone opens the same part of the codebase and asks the usual questions. Why is this data model shaped like this? Why is this rule handled in the backend instead of the frontend? Why is this integration synchronous? Why does this permission check live here? Why did the team choose this simple approach instead of something more flexible? The code can show what exists, but it rarely explains why it exists. That is where a lot of engineering context disappears. The Problem Is Not Always Missing Documentation When people complain about documentation, the usual diagnosis is that there is not enough of it. The README is outdated. The setup instructions are incomplete. The API docs are missing examples. The architecture diagram no longer matches reality. All of those problems are real. But I think there is another documentation problem that is easier to miss: the docs describe the system without preserving the reasoning behind it. This matters because software is full of trade-offs. A piece of code may look strange because it was written badly, but it may also look strange because it was solving a constraint that is no longer visible. Maybe the team chose a simpler data model because they were still validating the product. Maybe they avoided a generic abstraction because they had only one real use case. Maybe they accepted duplication because the two workflows looked similar but were expected to diverge. Without the reasoning, future developers have to guess. That guessing creates waste. So

One of the most annoying parts of backend development isn't building APIs. It's keeping the...

The problem Recently I was looking for an npm package to generate OpenAPI (Swagger) documentation for my existing TypeScript project. My biggest requirement was TypeScript type-to-schema conversion: I already have all my request and response types, so why should I maintain the same schemas again in OpenAPI? Zod support would be a nice bonus. After trying most of the existing solutions, I found they generally fall into two categories: 1. Runtime frameworks The most popular example is tsoa . Honestly, tsoa is one of the best OpenAPI generators available today: it understands TypeScript well, generates schemas automatically and detects status codes. There are also contract-first libraries like ts-rest , Zodios and express-zod-api . However, none of these solutions are agnostic when it comes to how you write your code — they all dictate the shape of your routes. 2. Manual generators The best-known example is swagger-jsdoc. You write raw OpenAPI next to your code in JSDoc comments: /** * @openapi * /users: * post: * ... */ swagger-jsdoc is simple and framework-agnostic, but it's too verbose and knows nothing about your types. Then I found a similar tool that solved the verbosity problem: @visulima/jsdoc-open-api . It parses much more readable JSDoc tags: /** * POST /users * @summary Creates a new user. * @tags Users * @bodyContent {User} application/json - User object to create. * @bodyRequired * @response 201 - User created successfully. * @responseContent {User} 201.application/json - The created user object. */ But it still doesn't care about your types. User here is just the name of a component you have to define elsewhere in your document. Why not parse the actual types at generation time? That question inspired me to create Autoswag . The solution - Autoswag Describe your routes with readable JSDoc, and let the generator convert your TS types along the way. It doesn't affect your runtime code in any way, works with any framework, and even with vanilla JS. This is w

I’ve always disliked writing documentation. Not because it’s hard, but because it’s repetitive. You write a function, you describe what it does, you give an example, and then you realize you need the same thing in another language because half your users don’t speak English. So I decided to automate it. The result is an API that takes source code as input and returns a clean Markdown README, API reference, or inline comments — in any of 13 languages. No templates, no manual translation. curl -X POST "https://ai-code-documentation-generator.p.rapidapi.com/demo" \ -H "x-rapidapi-host: ai-code-documentation-generator.p.rapidapi.com" \ -H "x-rapidapi-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"code":"def add(a,b): return a+b","code_language":"python","doc_language":"en"}' { "success" : true , "documentation" : "# Add Utility \n\n ## Overview \n A simple function to add two numbers..." , "quality_score" : 9 , "target_language" : "en" } It auto-detects the programming language (Python, JavaScript, Go, Rust…) and spits out a polished doc. The English output is solid, but seeing it generate accurate Japanese or German READMEs from the same code still feels like magic. The Tech Behind It Backend: Python + FastAPI, hosted on Northflank. AI Model: DeepSeek (via API). The model actually understands code structure, so generated docs aren’t just generic wrappers. Language Detection: Pygments for syntax highlighting + language guessing. Caching: 24-hour cache to avoid redundant calls and save cost. Security: Sensitive strings (API keys, passwords) are automatically redacted from the output. The whole thing is open source: https://github.com/zhaochangbo888/docgen-api Why I Didn’t Just Use ChatGPT You could absolutely paste your code into ChatGPT and ask for docs. But integrating an LLM directly into a CI/CD pipeline, or a VS Code extension, or a platform that needs programmatic access gets messy with rate limits, authentication, and output consistency. This API giv

My project's docs had rules. "One document, one responsibility." "Split anything over 45 lines." I wrote that. The day before yesterday. Here's how that was going. Folders with no README (no index): 25 out of 37 The folder holding our engineering rules: 11 files, zero index Documents breaking the 45-line rule: 47 Largest offender: 1,203 lines Writing a rule down does not make it a rule. Obvious, I know. But there is something about being handed a list of 47 documents where you personally broke your own rule that stops being funny halfway down. (The me of two days ago fully intended to follow it.) I rewrote the rules themselves, and the rules file hit 150 lines The plan was already clear: let a machine enforce this. Fail CI. Which meant writing the rules properly first. README required, folder layout, update obligations, what CI actually checks. By the time it was all in there, the rules file was over 150 lines. The rules file was breaking the 45-line rule. Now, if you say "well, the rules file is special, it gets an exemption" — what have you just done? You have created the precedent "the rules are exempt," and it is permanent from that day. From then on, every time someone crosses 45 lines, they get to say "the rules file does it too." And they're right. So I split it. Eight files, all under 45 lines. If I can't follow my own rule, the rule was never worth writing. The moment CI landed, 63 existing violations bared their teeth On to the real work: write the checker, wire it into CI. Run it, and of course: 63 violations Everything fails. All red. Files I'm about to touch and files nobody has opened in months, equally red. Humanity is offered two choices here. Fix all 63 first, then turn on CI (including the 1,203-line monster) Add an ignore list, silence the 63, move on Tempting, isn't it? Option 2. It was to me. A .lintignore with 63 lines in it and a comment saying "remove later." So when exactly are you removing that list? Think about what that file actually is.

AI agents no longer just answer questions — they book meetings, approve refunds, call APIs, update records, and chain together dozens of small decisions into a single outcome. Most of the time, this works quietly and well. But when something goes wrong, a troubling question surfaces: why did the agent do that? For a large share of deployed systems today, there's no good answer. The reasoning, the data consulted, the tools invoked, and the intermediate steps simply weren't recorded. This is the problem of undocumented agent decisions — and it's becoming one of the central risks of the agentic AI era. What "Undocumented" Actually Means An undocumented decision isn't necessarily a bad one. It's simply one that can't be reconstructed after the fact. In practice, this shows up in a few common ways: Output without reasoning. The system logs what the agent did, but not the chain of thought, tool calls, or data sources that led there. Ephemeral intermediate state. Multi-step agent chains often discard the "scratch work" between steps — the very material that would explain a decision — once the final output is produced. Reviewer blind spots. A human approves a final recommendation without ever seeing the reasoning that produced it, which looks like oversight but isn't meaningful oversight. No durable storage. Logs exist for a few days or weeks, then age out — so when someone asks for the record months later, it's gone. The common thread is a gap between acting and accounting for the action. This Is Becoming Urgent A few forces are converging to make this problem harder to ignore: Agents are doing more, autonomously. As agents move from single-turn assistants to systems that independently call APIs, touch databases, and trigger downstream workflows, the number of undocumented micro-decisions multiplies. A single customer request might now involve a dozen internal steps, each a potential decision point. Incidents are already happening. Surveys of enterprise AI deployments in 2