May 2026 Summaries

Enterprise documentation migrations are presented as primarily information-architecture challenges rather than simple content transfers, especially when organizations must manage sprawling page hierarchies, multiple products, legacy versions, custom components, internal links, SEO-sensitive URLs, and competing stakeholder priorities. ReadMe offers importer, manual, Git-based, and enterprise-assisted migration paths, with the enterprise option focused on discovery, audits, automated conversion, quality assurance, redirects, training, and rollout. Key decisions include whether to preserve or redesign navigation, how to map and protect URLs with server-side redirects, how to handle ReadMe’s independent fork-based versioning model, and which custom formatting or components should be rebuilt, simplified, or removed. The recommended preparation includes a sitemap, content and version inventory, OpenAPI specifications, traffic data for critical URLs, component lists, stakeholder roles, existing pain points, and timeline constraints, with the central goal of creating maintainable documentation that fits the destination platform rather than merely relocating existing material.

API documentation encompasses the reference material, guides, tutorials, examples, conceptual explanations, and release information developers need to understand, integrate with, and troubleshoot an API. Effective documentation serves both lookup and learning needs, using accurate specifications, intuitive terminology, runnable examples, clear authentication and error-handling guidance, documented limits, and predictable endpoint structures. The source distinguishes human-oriented documentation from API specifications such as OpenAPI and the machine-readable definitions that implement them, emphasizing that all should remain synchronized as APIs evolve. It recommends building documentation around observed developer journeys and support issues, choosing interactive portals where possible, organizing content for skimmability, and making references sufficiently structured for AI tools to interpret reliably. Regular testing, independent review, automated quality checks, and release-integrated updates help prevent documentation from becoming outdated, while interactive features such as live request testing can reduce onboarding time, support demands, and barriers to API adoption.

ReadMe has introduced branch reviews and notifications for Pro and Enterprise customers to help teams review documentation changes before publication and track who approved and merged them. Writers can request reviews from a branch, reviewers receive in-app alerts, and the Linter automatically identifies issues, while notifications cover review requests, approvals, and merges with configurable in-app and email preferences and a weekly digest. Enterprise customers receive additional workflow controls, including project- or group-level requirements for zero lint errors, teammate approval, or both, alongside configurable restrictions limiting merge access to admins or admins and editors; administrators can bypass these requirements for urgent changes. Enterprise editors and administrators can also use a centralized Reviews dashboard to view, search, and filter branches awaiting review across projects.

ReadMe introduced MDX-ish, a permissive documentation format intended to combine Markdown’s ease of use and fault tolerance with MDX’s ability to embed JSX components and interactive UI. The change follows a difficult migration from Markdown to strict MDX, during which ReadMe converted roughly 23 million existing pages but found that only about 65% could be transformed automatically because old documents often contained malformed HTML or syntax incompatible with JSX. MDX-ish allows Markdown, HTML, and JSX to coexist within the same document or element, rendering loose HTML when possible while recognizing PascalCase components and JSX-style brace attributes as JSX. Built with a custom tokenizer on micromark and transformations compatible with the remark ecosystem, the system makes parsing decisions before constructing an abstract syntax tree and relies on later rendering layers to normalize mixed HTML- and JSX-like attributes. Although the approach can produce less predictable output than strict MDX and does not support inline JSX component definitions, ReadMe considers visual debugging more accessible than syntax errors and stack traces. MDX-ish is paired with a redesigned editor that supports both syntaxes without invalid-MDX save errors, and it is now the default for new projects, available through upgrades for existing users, and being rolled out to Enterprise customers.

ReadMe’s GitHub AI Writer automatically monitors connected GitHub pull requests for changes that may require documentation updates, then creates proposed edits in a ReadMe review branch and posts a preview link on the related PR. It identifies undocumented user-facing features, outdated setup instructions caused by changed dependencies or configuration, and references to removed or deprecated functionality, while avoiding code review, linting, or generating documentation solely from comments. Unlike tools that require users to identify stale pages or manage documentation changes in separate repositories and workflows, the feature embeds drafting and review directly in ReadMe while keeping engineers informed through GitHub comments. It is intended for technical writers and developers who maintain documentation alongside product work, and is available on Pro, Enterprise, and legacy Business plans as a separate integration that can operate alongside GitHub bi-directional sync.

ReadMe has introduced the open-source @readme/cli to support Git-backed documentation repositories by validating their file and folder structure locally and in CI workflows. Its lint command checks issues including broken links, invalid frontmatter, malformed YAML or MDX, duplicate slugs, sidebar and ordering problems, missing components, and outdated OpenAPI-derived reference pages, while the --fix option resolves deterministic errors automatically. The CLI can synchronize Markdown reference pages with OpenAPI specifications, provide setup commands for CI services such as GitHub, GitLab, Bitbucket, CircleCI, and RWX, and post linting results on pull requests. A beta dev server offers hot-reloading local previews, and the tool is designed to work with AI coding agents such as Claude Code and Codex by providing format-aware validation and feedback for drafting or repairing documentation. The earlier rdme upload-focused CLI remains available for existing users, while the new tool reflects ReadMe’s shift to bidirectional Git synchronization.

ReadMe has launched a redesigned documentation platform focused on AI-assisted writing while retaining human review and control. The update includes a simplified admin interface with a unified sidebar, reorganized settings, and a customer-facing preview mode; a rebuilt Tiptap-based editor using “MDX-ish” to combine Markdown and MDX/JSX with inline AI editing; and branch workflows that isolate changes until they are reviewed and merged, including GitHub synchronization. Its new AI Writer monitors GitHub pull requests, creates documentation branches with suggested updates based on code changes, and lets teams review or automatically manage those branches alongside pull requests. ReadMe also introduced a CLI tool for terminal-based documentation workflows that identifies and can fix issues such as broken links, invalid frontmatter, duplicate slugs, and faulty MDX components, while supporting AI tools such as Claude and Codex. The company says these tools can be accessed through the editor, IDE, CLI, and GitHub-based workflows, with Bertie serving as a visual indicator for AI-enabled features.