https://valoryx.org/blog/ Recent content in Blog on Valoryx Hugo en Mon, 13 Apr 2026 00:00:00 +0000 https://valoryx.org/blog/ai-native-documentation/ Mon, 13 Apr 2026 00:00:00 +0000 https://valoryx.org/blog/ai-native-documentation/ Documentation has a maintenance problem. You write a guide, publish it, and within three months it’s outdated. The API changed. The config format was refactored. A dependency was replaced. The screenshots show a UI that no longer exists. The solution isn’t “write better docs” or “build a docs culture.” Teams have been trying that for decades. The solution is to make documentation aware of the code it describes — so when the code changes, the docs know about it. https://valoryx.org/blog/documentation-platform-cost/ Thu, 09 Apr 2026 00:00:00 +0000 https://valoryx.org/blog/documentation-platform-cost/ Per-seat pricing seems reasonable at first glance. Five users at $8/month? That’s $40. Your team can afford $40. But documentation is one of those tools where the number of people who should have access keeps growing. Engineers need to write. Product managers need to review. Support staff need to reference. New hires need to read and annotate. Suddenly you’re not at 5 seats — you’re at 50, and that “affordable” $8/seat is $400/month for a tool that stores text files. https://valoryx.org/blog/docs-for-open-source/ Mon, 06 Apr 2026 00:00:00 +0000 https://valoryx.org/blog/docs-for-open-source/ Open source projects live or die by their documentation. A library with great docs gets adopted. A library with a bare README and a “see the code” attitude gets forked by someone who writes better docs — or just ignored. But most documentation tools are built for companies, not OSS maintainers. They charge per seat, per page, or per workspace. For a project maintained by volunteers with zero budget, that’s a non-starter. https://valoryx.org/blog/documentation-search-works/ Thu, 02 Apr 2026 00:00:00 +0000 https://valoryx.org/blog/documentation-search-works/ You type a query into your documentation search bar. Results appear. But what happened between the keystroke and the results? For most documentation platforms, the answer is either “not much” (basic keyword matching that misses obvious results) or “a lot of infrastructure” (an Elasticsearch cluster that your ops team has to maintain). There’s a middle ground that most teams don’t know about: embedded full-text search. DocPlatform uses Bleve, a search library written in Go, compiled directly into the binary. https://valoryx.org/blog/single-binary-architecture/ Mon, 30 Mar 2026 00:00:00 +0000 https://valoryx.org/blog/single-binary-architecture/ Most documentation platforms ship as a stack. You get a Node.js application, a PostgreSQL database, a Redis cache, an Elasticsearch cluster for search, and an Nginx reverse proxy to tie it all together. Five services, five things that can break, five things to monitor, patch, and upgrade. DocPlatform ships as one file. Download it, run it, done. This isn’t a marketing trick. It’s an architecture decision we made on day one, and every design choice since then flows from it. https://valoryx.org/blog/keep-docs-up-to-date/ Thu, 26 Mar 2026 00:00:00 +0000 https://valoryx.org/blog/keep-docs-up-to-date/ Every engineering team has the same documentation problem. Someone writes thorough docs during a launch. Six months later, the API has changed, the configuration format is different, and three pages reference a feature that was renamed. Nobody updated the docs because updating docs is a separate task from writing code, and separate tasks get forgotten. The usual advice — “make documentation part of your culture” — doesn’t work. Culture doesn’t survive deadline pressure. https://valoryx.org/blog/docs-regulated-industries/ Mon, 23 Mar 2026 00:00:00 +0000 https://valoryx.org/blog/docs-regulated-industries/ If you work in healthcare, defense, finance, or any industry where data residency matters, you’ve already had the conversation: “Can we use this SaaS tool, or does it need to go through a six-month security review?” For most cloud documentation platforms, the answer is the review — and it often ends with “no.” The issue isn’t that cloud tools are insecure. Most of them are competent at security. The issue is control. https://valoryx.org/blog/bidirectional-git-sync/ Thu, 19 Mar 2026 00:00:00 +0000 https://valoryx.org/blog/bidirectional-git-sync/ Every documentation platform with a git integration page makes the same promise: your docs live in git, your team edits in the browser, and everything stays in sync. In practice, most of these integrations are one-way mirrors that fall apart the moment two people edit from different directions. We wrote about why this happens in a previous post. This one goes deeper into the solution: how Valoryx implements bidirectional sync using the Content Ledger pattern, and why this approach handles the scenarios that break other tools. https://valoryx.org/blog/mcp-documentation-guide/ Mon, 16 Mar 2026 00:00:00 +0000 https://valoryx.org/blog/mcp-documentation-guide/ Model Context Protocol (MCP) is an open standard that lets AI assistants interact with external tools and data sources through a structured interface. Instead of copying text into a chat window and hoping the model understands the context, MCP gives the assistant direct, typed access to your systems — read files, run searches, create content, all through well-defined tool calls. For documentation teams, this changes the workflow fundamentally. Your AI assistant stops being a text generator that works from stale context and becomes a participant that reads your actual docs, searches across your knowledge base, and makes edits you can review before they go live. https://valoryx.org/blog/internal-docs-developers-use/ Thu, 12 Mar 2026 00:00:00 +0000 https://valoryx.org/blog/internal-docs-developers-use/ Every engineering organization has internal documentation. And in most of them, that documentation is incomplete, outdated, or ignored. According to the 2024 Stack Overflow Developer Survey, a majority of developers consider poor or missing documentation a significant productivity barrier. This isn’t a discipline problem. It’s a tooling problem. Internal docs fail for specific, fixable reasons. The tools make writing painful. The content rots because nobody has a workflow for keeping it current. https://valoryx.org/blog/docs-should-be-in-git/ Mon, 09 Mar 2026 00:00:00 +0000 https://valoryx.org/blog/docs-should-be-in-git/ Here’s an inventory of what a typical engineering team keeps in git: Application source code Infrastructure definitions (Terraform, Pulumi, CloudFormation) CI/CD pipeline configurations Database migration scripts API specifications (OpenAPI, protobuf) Deployment manifests (Kubernetes, Docker Compose) Environment configuration templates And here’s what usually lives outside git: Documentation This is strange. Documentation describes the system. It changes when the system changes. It needs review, versioning, attribution, and the ability to roll back. Every other artifact that shares these properties lives in git. https://valoryx.org/blog/documentation-as-code/ Thu, 05 Mar 2026 00:00:00 +0000 https://valoryx.org/blog/documentation-as-code/ “Documentation as code” gets thrown around a lot. At its simplest, it means treating documentation the same way you treat source code: stored in version control, written in plain text, reviewed through pull requests, and built through CI/CD. But there’s a gap between the idea and actually doing it well. This guide covers what docs-as-code is, what approaches exist, and where each one falls short. Why Docs-as-Code Matters Software teams already have workflows for managing change. https://valoryx.org/blog/self-host-docs-5-minutes/ Mon, 02 Mar 2026 00:00:00 +0000 https://valoryx.org/blog/self-host-docs-5-minutes/ Most self-hosted documentation tools require a database, a reverse proxy, and half an afternoon of YAML editing before you see a welcome screen. DocPlatform is a single Go binary with zero external dependencies. This tutorial takes you from nothing to published documentation in about five minutes. Prerequisites You need a Linux, macOS, or Windows machine. That’s it. No Docker, no PostgreSQL, no Node.js runtime. DocPlatform compiles to a single static binary — the Go runtime is embedded. https://valoryx.org/blog/notion-alternative-self-hosted/ Sun, 01 Mar 2026 00:00:00 +0000 https://valoryx.org/blog/notion-alternative-self-hosted/ Notion is everywhere. Design teams use it for briefs. Product teams use it for roadmaps. Marketing teams use it for content calendars. And increasingly, engineering teams use it for documentation — technical specs, runbooks, onboarding guides, API references. It works, up to a point. Then you hit the edges, and the edges are sharp. This post is for teams who’ve hit those edges and are looking for something better — specifically for technical documentation that belongs in a git repository, not a proprietary database. https://valoryx.org/blog/self-hosted-docs-guide/ Fri, 27 Feb 2026 00:00:00 +0000 https://valoryx.org/blog/self-hosted-docs-guide/ Self-hosted documentation is having a moment. After years of SaaS platforms raising prices, changing terms, and shutting down without warning, more teams are choosing to run their own documentation infrastructure. The reasons are straightforward: data ownership, cost control, compliance, and the comfort of knowing your knowledge base won’t disappear when a startup runs out of funding. But the self-hosted documentation landscape is crowded and confusing. There are wiki platforms, static site generators, knowledge bases, and hybrid tools — each with different trade-offs. https://valoryx.org/blog/gitbook-vs-valoryx/ Wed, 25 Feb 2026 00:00:00 +0000 https://valoryx.org/blog/gitbook-vs-valoryx/ GitBook is one of the most popular documentation platforms for developer teams. It has a polished editor, solid collaboration features, and good-looking published docs. If you’re evaluating documentation tools, it probably showed up on your list. We built Valoryx to solve problems that GitBook doesn’t address — primarily around git ownership, self-hosting, and pricing transparency. But we want to give you an honest comparison, not a marketing page. Here’s where each tool shines and where each falls short. https://valoryx.org/blog/why-git-sync-breaks/ Sun, 22 Feb 2026 00:00:00 +0000 https://valoryx.org/blog/why-git-sync-breaks/ If you maintain technical documentation, you’ve probably been burned by this promise: “Full git integration.” You connect your repo, make some edits in the web UI, push a commit from your IDE — and everything falls apart. Merge conflicts. Lost edits. Pages that silently revert. A sync status that says “up to date” while your content diverges. This isn’t a bug in any single product. It’s a fundamental design flaw in how most documentation platforms think about git.