Loading…
Topic
15 posts about Documentation. Every summary links to the original.
See the idea
Backstage can act as an engineering context boundary: catalog entities, templates, and TechDocs inform an agent before it proposes changes. See where validation and review fit.
The Good Stuff
Paid picks we use ourselves. Links carry a referral code — a subscription through one earns us a commission at no extra cost to you.
Newest first
Most companies invest heavily in acquisition content but neglect post-signup support, leaving customers with poorly written FAQs and contributing to high churn rates. Intercom advocates replacing isolated how-tos with best practice content that teaches customers how to get the most from a product. The approach includes giving the entire lesson, using real-life customer examples, writing about how the team uses the product, mirroring customer language, and revisiting content often. Practical techniques include breaking tasks into quick wins, using bullet points and screenshots, embedding videos, and leveraging a bot for automated answers. The goal is to empower customers to self-serve, reducing support contacts and building long-term loyalty.
Dropbox has launched a modernized API documentation site at https://docs.dropboxapi.com, rebuilt to make integration faster and more intuitive. The new documentation features interactive API testing that lets developers set parameters, issue API calls, and view real responses from the Dropbox API directly in their browser without switching tools. An embedded AI assistant offers instant help with endpoint questions, troubleshooting, and code examples, while the documentation integrates with MCP (Model Context Protocol) so AI tools like Claude Code and Cursor can access up-to-date API information. Through the MCP server at https://docs.dropboxapi.com/_mcp/server, developers can connect their AI assistants to answer questions, explore the API, and assist with integrations using information directly from the docs. The update delivers a clean, responsive, searchable interface that brings endpoints, types, schemas, and related documentation together, with improved navigation, and provides comprehensive information including detailed error responses, type definitions, and full request/response schemas.
Twilio used AI to update 1,138 error-code documentation pages over about 12 weeks, with a human reviewing every change. The team first scored roughly 2,692 pages with a deterministic script covering structure, content, and resources, then routed low-scoring pages to an LLM pipeline while sending borderline pages to human review. That pipeline used OpenAI's gpt-5.4 via the Responses API, generated full-file responses, sanitized them, converted them into git apply patches, linted results, and rejected any page whose code snippet fingerprint changed. Small-batch pull requests, tracking files, local-modification checks, and named reviewers limited duplicate work and kept approval in the workflow. Across about 27 pull requests from March to May 2026, the process marked 1,138 error codes complete, while the team acknowledged that human review was the quality bar and that future scaling would benefit from an automated evaluation harness and diff-based generation.
Supabase found that coding agents increasingly use its documentation to configure projects, creating risks when pages omit or bury critical instructions. To measure this, the team built an evaluation for the Row Level Security (RLS) guide, running an agent through realistic tasks and grading outcomes with checklist-based and agent-based judges. The initial runs found unauthenticated anon access with write privileges across tables and showed that test guidance was skipped when separated from the policy code. Supabase responded by adding procedural revocation steps, explicit policy snippets, and colocated test examples; the eval then passed the affected checks. The project concludes that agents and humans both benefit from selective-reading-aware structure, clear sections, explicit signposting, and recurring documentation evaluations, with the RLS scenario moving into the public supabase/evals benchmark.
The author recounts a career path from creative interests and technical writing to developer relations, emphasizing that storytelling remained central while the audience changed. She began by producing API documentation, user guides, onboarding content, and other developer resources, then joined JDoodle, where conversations with developers shifted her focus from writing for them to connecting with them. Attending events and conferences, giving product demos, staffing booths, participating in community conversations, organizing hackathons, and running internal events helped her discover that developer advocacy matched her strengths in empathy, clear storytelling, and helping people succeed. She now announces a new role at Okta, where she will work with developers, creators, builders, and community members in identity and security while creating content, attending events, learning, and building connections.
Grab adopted Docs-as-Code in early 2021 to bring technical documentation into engineers’ code workflows, addressing scattered sources, version confusion, discoverability, and quality gaps. Documentation was written in Markdown, stored in version-controlled repositories, reviewed through merge requests, checked in CI/CD, and surfaced through an internal developer portal. As engineering scaled, decentralized repositories produced inconsistent structures and terminology, unreliable organization-wide quality automation, aging content, and tracking problems when source locations changed. Grab therefore moved to a centralized repository while retaining Docs-as-Code, adding shared templates and linters, unified search through fuzzy title lookup and Glean, automated synchronization during migration, and training and feedback programs. The post concludes that decentralized, centralized, or hybrid models fit different contexts, with centralization emphasizing discoverability, governance, consistency, ownership metadata, and analytics.
AI-driven customer service depends on knowledge management because a Service Agent needs accurate product, feature, policy, and troubleshooting information to resolve queries end to end. The guide divides the work into two phases: building a knowledge base, and maintaining, optimizing, and scaling existing content. It recommends using support conversations and tools such as Fin Recommendations to identify gaps, prioritize FAQs, onboarding guides, troubleshooting material, and other resources, then centralize content and control what the Agent can use. Ongoing practices include scheduled reviews, a request log, launch-planning updates, consistent terminology, audience targeting, and contact details for escalation. The stated conclusion is that knowledge management should be a continuous core service function, with improvements producing more resolutions, better data, and further opportunities to refine support.
Chronicle’s Product Hunt launch aimed for a few hundred upvotes but reached number one and generated a waitlist of more than 100,000 signups. The remote team used Notion as a launch “mission control,” expanding an initial planning page into a database with status and due-date properties, assigned owners, collaborator tags, asset links, social copy, and calendar views. The shared hub coordinated feature timelines, asset publication, emails, LinkedIn posts, announcements, pre-launch instructions, and real-time launch-day updates without losing a single source of truth. Templates turned tasks into reusable pages containing creative files, drafts, and strategy notes, while the broader workspace also stored customer interview transcripts and marketing work. The team attributes the result to early preparation, careful copy and assets, coordinated support from its ecosystem, and treating the launch as a company-wide event; it says the process enabled speed, alignment across time zones, and documented repeatability.
European organisations face a knowledge paradox: 97% of surveyed business leaders say knowledge management is critical, but only 28% report having a coherent strategy, with poor practices costing up to €16,000 per employee annually. Interviews with leaders in France, Germany and the UK connect scattered information across people and tools to slower progress, weaker decision confidence, repetitive work and lost institutional knowledge. The post argues that centralised knowledge is a prerequisite for effective AI, noting that 56% of organisations already use AI for knowledge management and 29% are piloting it, while incomplete documentation can undermine deployments. Recommended practices include explaining the personal benefit of documentation, designing systems that pull participation rather than enforce compliance, and treating knowledge as a shared organisational asset. Examples include Nelly, Above, UnternehmerTUM and EGYM using simpler documentation workflows and shared spaces to reduce silos and keep information current.
Lean teams competing with larger companies cannot match their rivals’ hiring capacity or budgets, prompting a reassessment of success based on individual impact rather than headcount. Adding tools, integrations, and AI can create a “multi-tool trap,” scattering information and accelerating mistakes when infrastructure and direction are weak. The recommended response is to consolidate work and knowledge into connected systems, invest in documentation such as roadmaps, specifications, requirements, and strategic memos, and choose infrastructure improvements over reflexive hiring. These foundations give AI usable context, preserve decisions through organizational change, and help individuals operate as effective generalists; the conclusion is that scalable infrastructure can let one person do work that once required three, while making each future hire more impactful.
Companies can lose speed when knowledge remains in silos, making work harder to complete quickly. A Harvard Business Review survey cited in the text found that 44% of respondents think their company manages knowledge well, while 3% use AI to help. Conversations with Rohit from OpenAI, Jennifer from Slack, and Kristen from Hinge point to organizing information around actual work, establishing clear locations for knowledge, and designing systems people will use. The examples include Hinge’s weekly “Documentation Fridays” and Slack’s inclusion of documentation in performance expectations. Recommended actions are to define a source of truth, map where information lives, use templates, build sharing into routines, and recognize contributors; the stated payoff is faster movement, more innovation, and learning from experience.
Grab introduced a rich-text, WYSIWYG editor in its TechDocs portal to help non-engineering contributors work within a Docs-as-Code process despite limited familiarity with Markdown and GitLab. The editor keeps GitLab as the central storage system, uses Lexical to import and export Markdown, and supports page reordering, renaming, deletion, formatting, diagrams, and switching between normal and Markdown views. Three user journeys cover editing existing TechDocs and creating stand-alone or entity-linked documentation, with GitLab OAuth2, merge-request creation, repository access checks, and scheduler-based entity-catalog registration after merges. A phased rollout added drafts, image uploads, diagram integrations, concurrent-session visibility, and live preview, while pending-MR displays and conflict-resolution tools address collaboration risks.
Puzzle presents Notion as the central operating system for its startup, using it as a single source of truth for company knowledge, workflows, and collaboration. The playbook describes eight practices, including integrating tools and legacy content, standardizing recruiting and onboarding, supporting asynchronous communication, organizing teamspaces, building documentation habits, applying AI, and connecting task management to strategic priorities. Its implementation relies on templates, checklists, permissions, comments, @mentions, automations, relations, rollups, database views, formulas, and verification controls. For a team of 50+ employees, Notion AI reportedly saves about ten minutes per query; five daily queries per person are calculated as more than twenty-one hours saved weekly across the company. The conclusion recommends starting with one area, such as meeting documentation or onboarding guides, before expanding.
Grab’s TechDocs working group describes a two- to three-year effort to make high-quality documentation part of everyday engineering culture. Built on the Helix engineering platform and a Docs-as-Code workflow, TechDocs gives teams a central place to create, manage, and access technical content, while user research informs tool and process changes. The programme combines inventory-taking, policy, team enablement, and recurring measurement, using broad surveys and 1:1 observation to identify fragmented tools, weak ownership, search problems, and maintenance gaps. Research found that only 2% of engineers reported resolving 80–100% of on-call questions through documentation; later initiatives included an editor, writing training, practical workshops, and recognition tied partly to documentation quality and on-call-bot response accuracy. Planned work includes better navigation, training, feedback loops, and editing workflows.
The post presents Livebook as an interactive way to document the central logic of an Elixir or Phoenix application, helping new developers understand and explore code alongside existing documentation and tests. Using a TicTac example, it documents and executes the GameState module and struct, then describes and demonstrates a Horde-managed GenServer that runs the game state. Livebook connects to an existing project through a Mix standalone runtime, providing Elixir code completion, Markdown explanations, execution, and access to operations such as Ecto queries, context calls, and starting GenServers. The resulting notebooks are plain Markdown files, can be stored in source control, and support experimentation, reviewable diffs, and collaborative editing. The setup described requires Elixir 1.12: install Livebook with mix escript.install hex livebook, start livebook server, and connect through the locally generated token URL.
The best engineering reads, once a week.
