# technical-documentation Published articles for technical-documentation. This is one page of public article previews, not the complete archive. Follow Next page to continue. Summaries are not the original full articles. ## The Importance of Documentation in B2B API Adoption DevFeed: [The Importance of Documentation in B2B API Adoption]() Original publisher: [Read original article]() Author: Anila Zaidi Published: 2026-06-23T16:15:00Z Content type: opinion Language: en Sources: [Squarespace](), [Squarespace Engineering Blog]() Topics: [Documentation](), [API](), [Support](), [Feathers]() Tags: [api](), [b2b](), [documentation](), [support](), [technical-documentation]() ### AI overview This article explains how improving public Commerce API documentation reduced support tickets and how documentation for the Domain Reseller API became a product asset. It argues that effective documentation can reduce support questions, align teams, and help potential B2B partners evaluate an API. ### Source excerpt We read reviews before buying a TV, a sweater, almost anything. Businesses do the same - potential enterprise partners evaluate APIs through every piece of content they come across. So, what happens when you improve all of it? ## Introducing CDP: The New Espressif Documentation Website - Now Available to Customers! DevFeed: [Introducing CDP: The New Espressif Documentation Website - Now Available to Customers!]() Original publisher: [Read original article]() Author: John Lee Published: 2025-07-08T00:00:00Z Content type: release Language: en Sources: [Blog on Developer Portal]() Topics: [Documentation](), [Espressif](), [Website](), [AI Chat](), [Chat Bot]() Tags: [ai](), [announce](), [article](), [blog](), [chat](), [documentation](), [espressif](), [features](), [information](), [platform](), [responses](), [search](), [technical](), [technical-documentation](), [verify]() ### AI overview Espressif introduces its Centralized Documentation Platform (CDP), a unified website for technical documentation. The platform combines document browsing and search with an AI-powered chatbot that answers from Espressif documentation and provides source references. ### Source excerpt This article introduces Espressif's new Centralized Documentation Platform (CDP) -- a unified site for all technical documentation, featuring enhanced search, integrated chatbot support, and improved feedback tools. ## Using AI for Technical Documentation: Capabilities, Limitations, and Human Review DevFeed: [Using AI for Technical Documentation: Capabilities, Limitations, and Human Review]() Original publisher: [Read original article]() Author: Emma Adler Published: 2025-04-02T00:00:00Z Content type: opinion Language: en Sources: [Mintlify Blog]() Topics: [Artificial Intelligence](), [Documentation](), [Generative AI](), [Prompt Engineering](), [Tutorial]() Tags: [ai](), [ai-trends](), [docs](), [generative-ai](), [hallucinations](), [technical-documentation](), [tutorial]() ### AI overview The article examines how AI can assist with technical documentation, including API references, tutorials, and how-to guides. It argues that AI remains limited by problems with context, nuance, reliability, accuracy, audience adaptation, and consistency, so effective use requires structured prompts, iterative refinement, and careful human review. ### Source excerpt The perception of writing as a profession changed with the proliferation of AI. Generative AI platforms and tools like ChatGPT are now used to create and rewrite content at scale. ## #51 - My developer blogging journey so far DevFeed: [#51 - My developer blogging journey so far]() Original publisher: [Read original article]() Author: Shreyas Patil Published: 2025-02-18T14:10:44Z Content type: opinion Language: en Sources: [Shreyas Patil's Blog]() Topics: [Learning](), [Android](), [Firebase UI](), [Open Source](), [GitHub](), [Realtime Database](), [SDKs]() Tags: [android](), [androiddev](), [blog](), [blogging](), [code](), [community](), [content-creation](), [developer](), [development](), [firebase-database](), [firebase-ui](), [flutter](), [github](), [journey](), [kotlin](), [open-source](), [technical-documentation](), [technical-writing-1](), [writing]() ### AI overview A personal account of the author's blogging journey, beginning with an Android project in 2019 and a contribution to FirebaseUI-Android that led to a first published technical article. The author describes how writing supported learning, career development, and sharing with the developer community. ### Source excerpt A personal account of my journey as a tech blogger, from my first post in 2019 to becoming a GDE. Insights on English barriers, criticism, and why sharing matters. ## Markdown vs. DITA: Balancing Simplicity and Structure in Technical Documentation DevFeed: [Markdown vs. DITA: Balancing Simplicity and Structure in Technical Documentation]() Original publisher: [Read original article]() Author: Niklas Begley Published: 2024-06-06T07:00:00Z Content type: comparison Language: en Sources: [Doctave - Build beautiful developer portals with docs-as-code]() Topics: [Markdown](), [Documentation](), [XML](), [HTML](), [OpenAPI Specification]() Tags: [blog](), [docs-as-code](), [documentation](), [html](), [markdown](), [openapi](), [technical](), [technical-documentation]() ### AI overview This comparison examines Markdown and DITA as authoring choices for technical documentation. It presents Markdown as easy to learn and widely supported, while describing DITA as a more structured XML standard that supports content reuse, document consistency, and publishing in multiple formats, with a higher learning curve. ### Source excerpt When embarking on a new documentation project, one of the first, and quite consequential choices you have to make is what tools and formats to pick. Do you go with Markdown, the ubiquitous and light-weight markup language with a low barrier to entry, or do you instead reach for an authoring system like DITA that lets you enforce structure and reuse content from day one? In this post we're going to look at both options and evaluate the pros and cons of both approaches, and when one might choose one over the other. What is Markdown? Markdown was originally developed by John Gruber back in 2004. It was designed as an easy way to convert text into HTML easily. Here is John describing Markdown in the introduction: Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML). 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 # Rocket Launch Sequence 1. **Pre-launch Jitters** - Double-check that the pointy end is facing up - Ensure the rocket isn't just a giant firework - Cross fingers and hope for the best 2. **Blastoff!** - Light the candle and watch the show - Try not to think about the astronomical fuel costs - Wave goodbye to the rocket (and your paycheck) 3. **Celebrate or Commiserate** - If the payload reaches orbit, break out the champagne - If not, break out the tissues and start drafting the apology email - Either way, start planning for the next launch (and budget) Example Markdown snippet Since then, Markdown has exploded in popularity. It has become the lingua franca for all kinds of technical content and blogs. Developers have embraced the simplicity of Markdown. Most new programming languages support Markdown as part of their docstrings, OpenAPI supports Markdown in description fields, and most static site generators have built-in Markdown support. The ecosystem of Makdown tooling is vast. This is why the docs-as-code movement has mo ## The path to structured content with Markdown DevFeed: [The path to structured content with Markdown]() Original publisher: [Read original article]() Author: Niklas Begley Published: 2024-06-06T07:00:00Z Content type: tutorial Language: en Sources: [Doctave - Build beautiful developer portals with docs-as-code]() Topics: [Markdown](), [Parser](), [Parsing](), [XML](), [Documentation]() Tags: [authoring](), [blog](), [documentation](), [markdown](), [structure](), [structured](), [syntax](), [technical](), [technical-documentation]() ### AI overview The article argues that Markdown has an underlying structure that is often hidden from authors, making it more similar to XML-based structured authoring than commonly assumed. It demonstrates how Markdown is transformed into an abstract syntax tree and represented as a tree-shaped JSON structure. ### Source excerpt This post was inspired by the Pros and Cons of Using Markdown for Technical Documentation Panel Discussion with Ed Marsh, Eric Holscher, and Fabrizio Ferri-Benedetti. Around the ~40 minute mark the discussion moves onto how to maintain a consistent style with Markdown documentation, especially in larger teams. The panel agrees that currently there are no clear ways to enforce a specific document structure when using Markdown. Fabrizzio then on goes on to say (54:15): Some day, someone is going to figure out a way to seamlessly grow Markdown into something that can mature into structured content I've been thinking about this a lot, and my claim is that Markdown and XML (which is traditionally used for structured authoring) are more similar than you would initially expect, and that the dream of adding validations and structure to Markdown is perhaps not too far away. The structure behind Markdown There's a commonly held belief that Markdown is not structured. There is some truth to this, but I'd argue it's more the case that the structure is hidden. While with most XML-based authoring tools you are manipulating the structure directly (or through a WYSIWYG editor), with Markdown we are one level removed from the actual underlying structure. To demonstrate, let's take a look at a quick example at how Markdown is actually almost equivalent to XML, if you squint a little. Let's take this Markdown content. 1 2 3 4 5 # Hello, world This is a paragraph **with some bold text** and this is an image When this Markdown is processed into HTML, it goes through a number of transformations. The first thing that happens is that the Markdown is converted into an Abstract Syntax Tree. This means taking the raw text of the Markdown, and converting into something more structured that a program can manipulate. Each Markdown parser does this a little bit differently, but we can see this in action with, for example, the AST Explorer tool. Let's take Markdown above, and paste it ## How we are driving up the quality of internal technical documentation at Volvo Cars DevFeed: [How we are driving up the quality of internal technical documentation at Volvo Cars]() Original publisher: [Read original article]() Author: Gary Niemen Published: 2024-02-26T11:39:27Z Content type: article Language: en Sources: [Volvo Cars Engineering - Medium]() Topics: [Documentation](), [Developer experience](), [engineering-culture]() Tags: [backstage](), [blog-post](), [developer-experience](), [docs-as-code](), [documentation](), [engineering](), [platform-engineering](), [technical-documentation](), [technical-writing](), [writing]() ### AI overview The article describes how a small technical-writing team at Volvo Cars is improving the quality of internal technical documentation for more than 4,500 software engineers. It presents treating documentation like code as one part of a broader approach to scaling technical writing. ### Source excerpt How we are driving up the quality of internal technical documentation at Volvo Cars -- with just a few technical writersTreating docs like code is part of it -- but not all of itGenerated by Deep Dream Generator by Author There are many components to a great developer experience. One of them, I think we can all agree, is to have quality internal technical documentation. But how to get to that place? Few engineering organisations prioritise recruiting technical writers above software engineers. And software engineers, typically, and perfectly understandably, prefer to be coding rather than writing. The answer in the tech industry of today -- is to find a way to scale tech writing. Consider this... Many years ago, when I was working as a technical writer at one of the world's leading IT companies, the sacred ratio was one tech writer for 8-10 developers. Later, when I moved on and started working as a documentation lead in FinTech, I tried to get the company to implement this ratio -- but, alas, it was never going to fly. We settled on about 1 to 30. I was not too pleased. If only I had known what was to come. When I started working in big tech, it was more like 1 to 1000. And now at Volvo Cars, it is -- well that's what this blog post is all about. How just a few technical writers (two within a centralised developer experience function and one focusing on a specific part of the organisation) are driving up the quality of internal technical documentation among 4500+ software engineers at Volvo Cars. (What's the ratio now, huh?) As we'll describe in this blog post, moving to treating docs like code is one key component of scaling technical writing, but not the only one. Implement docs like code About five years ago when at a previous company, I stumbled across Google technical writing manager, Riona MacNamara's talk from the 2015 Write the Docs conference, Documentation, Disrupted: How Two Technical Writers Changed Google Engineering Culture. Riona was talking about solving p ## Outro: What You Did and What's Next DevFeed: [Outro: What You Did and What's Next]() Original publisher: [Read original article]() Author: Anila Zaidi Published: 2023-12-06T19:22:00Z Content type: tutorial Language: en Sources: [Squarespace](), [Squarespace Engineering Blog]() Topics: [Documentation](), [Tutorial](), [Information Architecture]() Tags: [collection](), [community](), [existing](), [information-architecture](), [technical-documentation](), [technical-writing]() ### AI overview This tutorial outro recaps the process of drafting, revising, testing, and publishing technical documentation. It then introduces next steps for organizing documentation collections with information architecture, revising existing documentation, and developing technical writing skills. ### Source excerpt The outro recaps what you did - write technical documentation! - and introduces next steps like organizing a collection of documentation, revising existing content, and expanding your technical writing skills by joining the technical writing community. ## Part 4: Test, Edit, And Publish Content DevFeed: [Part 4: Test, Edit, And Publish Content]() Original publisher: [Read original article]() Author: Anila Zaidi Published: 2023-12-05T19:46:00Z Content type: tutorial Language: en Sources: [Squarespace](), [Squarespace Engineering Blog]() Topics: [Documentation](), [Tutorial](), [Testing]() Tags: [documentation](), [technical-documentation](), [technical-writing](), [testing](), [tutorial]() ### AI overview This tutorial explains how to turn technical writing into technical documentation by testing, editing, approving, and merging the content. It presents the A-TEAM process and emphasizes testing content against the reader's goal and using a style guide during editing. ### Source excerpt After completing Parts 1, 2, and 3 of this tutorial, your once blank page now has technical writing - you're officially in the home stretch! Technical writing on a page becomes technical documentation only after you test, edit, and publish the content. Do not underestimate the exponential payoff that comes from testing and revising content. More than one technical writer can claim that revision has either uncovered bugs in software or improved it. ## Part 3: Draft Content That's Accurate, Consistent, And Concise DevFeed: [Part 3: Draft Content That's Accurate, Consistent, And Concise]() Original publisher: [Read original article]() Author: Anila Zaidi Published: 2023-11-28T17:59:00Z Content type: tutorial Language: en Sources: [Squarespace](), [Squarespace Engineering Blog]() Topics: [Documentation](), [Tutorial]() Tags: [documentation](), [glossary](), [guides](), [how-to](), [technical](), [technical-documentation](), [technical-writing](), [tutorial](), [writing]() ### AI overview Part 3 of a technical writing series explains how to draft documentation that is accurate, consistent, and concise. It recommends maintaining a glossary, defining terms and personas, using consistent terminology, and keeping content focused on readers' needs. ### Source excerpt In my opinion, creating good headings and organizing them in a way that's helpful to readers is much more challenging than drafting content. So pat yourself on the back for completing Part 2 of this series and making it to Part 3. 👏 👏 👏 However, there are three things that undo exceptional headings and structure in technical documentation: content that is inaccurate, content that's inconsistent, and content that's inflated. ## Part 2: Use Good Headings For Structure And Scanning DevFeed: [Part 2: Use Good Headings For Structure And Scanning]() Original publisher: [Read original article]() Author: Anila Zaidi Published: 2023-11-21T15:35:00Z Content type: tutorial Language: en Sources: [Squarespace](), [Squarespace Engineering Blog]() Topics: [Documentation](), [Tutorial]() Tags: [documentation](), [reading](), [structure](), [technical-documentation](), [tutorial]() ### AI overview This tutorial explains how good headings and content structure make technical documentation easier to scan. It discusses headings as a blueprint and map, their role in automatically generated tables of contents, and how structure should reflect the content type and the reader's goal. ### Source excerpt Part 1 of this tutorial introduced you to the content types that are most common in technical documentation. You also evaluated a real-life example as a reader, and you may have realized how headings are essential to a good reader experience. It's because readers on the web do not read - they scan ¹ . People actually read 25% slower on the web² and they only read 20% of the content on a page³. (This data is from 2008; I'm scared to know the percentage today.) ## Documentation Has Different Meanings and Requires Context-Specific Practices DevFeed: [Documentation Has Different Meanings and Requires Context-Specific Practices]() Original publisher: [Read original article]() Author: Niklas Begley Published: 2023-10-17T07:00:00Z Content type: opinion Language: en Sources: [Doctave - Build beautiful developer portals with docs-as-code]() Topics: [Documentation](), [Development](), [code comments](), [API](), [Markdown](), [toolchain]() Tags: [api](), [best-practices](), [blog](), [code-comments](), [documentation](), [markdown](), [technical-documentation](), [toolchain]() ### AI overview The article argues that "documentation" can refer to different materials, from README files and code comments to developer portals, manuals, and API references. Because these forms serve different audiences and contexts, advice to reduce or replace documentation with automation cannot be applied universally. ### Source excerpt There was a post submitted to the Orange Website™ the other week with the title "Delete half your documentation" (HN thread here). The author talks about how documentation inherently has a cost, and how we should minimize the amount of documentation we need. It becomes outdated, requires maintenance, and "nobody reads it anyway". Instead, they argue, we should use type annotations, tested examples, and other methods to remove the requirement for manually maintaining documentation. Some of these arguments have some merits in the right context. But what really caught my eye in the post was this line: "When I say 'documentation', I mean all forms of it, including README, Markdown files, docstrings, and code comments." Hang on. This is not all forms of documentation! And we certainly cannot apply these rules universally. Documentation is in the eyes of the reader I recently Tweeted about the confusion that can happen when people use the word "documentation" to refer to different things. The word "documentation" has so many meanings depending on who you're talking to. To one person it's a single README file. To another, it's a full blown dev portal with guides and API references. Causes legitimate confusion sometimes -- Niklas Begley (@NiklasBegley) September 6, 2023 The post mentioned above is a great example of this phenomenon. The author clearly had the view that "documentation" means code documentation: docstrings, and other supplementing information you can include in or generate from raw source code. This is quite natural for software developers, since it's the kind of documentation they are used to producing themselves. And for their case, perhaps relying on automation over prose to ensure your documentation is in order is a good idea. But what about developer portals, manuals, or API references? Surely a technical writer documenting a complex developer toolchain should not apply the same thinking and "delete half their documentation"? An overloaded term Technical