August 2026 Summaries

Technical documentation remains accurate when teams distinguish between content that should be generated and content that requires human authorship, rather than maintaining all material manually as systems change. Using the Diátaxis framework, the guide separates documentation into tutorials, how-to guides, reference material, and explanations, arguing that API reference should be derived automatically from machine-readable specifications while conceptual guidance, procedures, and context should be written and reviewed by people. It recommends identifying specific audiences early, using templates for each content type, storing authored material in version-controlled Markdown or MDX, and enforcing style, specification, link, and code-sample checks through continuous integration. Effective procedural documentation emphasizes runnable examples, prerequisites, expected results, troubleshooting, and consistent terminology, while explanations add the practical judgment that API specifications cannot convey. The guide also notes that documentation increasingly serves AI coding agents through formats such as llms.txt, raw Markdown endpoints, MCP servers, and API catalogs. Fern is presented as a platform that generates API references, multilingual code samples, and AI-readable documentation from API definitions while supporting Git-based conceptual content, access controls, and audience-specific filtering.

OpenAPI type declarations function as instructions for code generators as well as documentation, making schema precision central to the quality and safety of generated SDKs. The discussion explains that OpenAPI 3.0 uses a modified JSON Schema subset, while 3.1 adopts JSON Schema 2020-12 and replaces features such as `nullable` with explicit null types, adds `const`, and changes several constraint syntaxes. It emphasizes modeling known object properties, applying recognized formats to strings and numbers, avoiding JSON numeric `int64` identifiers in JavaScript clients, and distinguishing optional, nullable, and defaulted fields, particularly for PATCH operations. Enums provide native typed values but can make newly added server values breaking for older clients, while `oneOf` with a discriminator is presented as the most reliable approach for type-safe polymorphic SDK models; `anyOf` commonly produces loose types and `allOf` represents intersection-based composition. Validation constraints, request/response access controls, named reusable schemas, typed error responses, and careful money modeling can further improve generated clients. Fern is described as supporting OpenAPI 3.0 and 3.1, preserving discriminators, handling PATCH field states, and adding extensions for enum metadata and type naming, with the overall recommendation that API authors evaluate schemas by their generated developer experience rather than validator or linter compliance alone.

Devin Logan describes how Fern uses Claude Skills to scale a one-person marketing content operation producing roughly 24,000 words monthly across case studies, launch posts, customer Slack changelogs, employee profiles, and engineering blog edits. Unlike Fern’s documentation, which relies on a shared AGENTS.md file for broadly applicable rules, marketing uses separate, format-specific skills because each content type has distinct audiences, structures, and goals. Logan found that pursuing perfectly publishable AI drafts created overly complex skills without eliminating the need for editorial work, and instead treats verbose but factually structured drafts as useful starting points that are easier to refine than sparse ones. Human editing remains essential for product knowledge, audience judgment, precision, and deciding whether to foreground a feature’s benefit or its technical detail, while each completed session informs updates to the relevant skill. The approach also distinguishes between tasks suited to AI-assisted drafting or feedback and personal writing that requires the author to develop an original argument independently, emphasizing that automation should support rather than replace editorial thinking.