When I’m tasked with documenting an API or technology, I have a general pattern of work I follow, just like every writer. Sometimes, a job dictates a specific workflow, but this is the flow I follow when I’m allowed to choose my own path. It’s a multi-step process that leads me from ideation through to completion, and has brought me good and well-received results in the past. I don’t always follow this exact path; sometimes I combine steps, and sometimes steps can be skipped because they’ve been dealt with by others or there’s nothing to be done for that step.
I talk about AI a little bit in this post. I don’t use AI much yet, as I’m still experimenting with the best way to add it to my workflow. Below, I include information about ways I have used AI with some success within my process, but the process as a whole isn’t AI-centric. That’ll continue to evolve over time as generative AI technology matures and matures, and as I adapt my process to incorporate it more thoroughly.
In this post, I briefly touch on each step of my process, without diving into too much detail. Obviously, this may differ from how you or your company go about things, but this at least should offer some things to consider. I may dive deeper into individual steps of this process in future posts.
Step 1: Prepare
I like to start by reviewing specifications, design notes, emails I’ve exchanged with the engineering team, and so on. I don’t study them in depth, because that takes time and realistically it’s not the best way for me personally to retain this information. Instead, I use this as a time to spot obvious complications that warrant additional requests for details before I get started. I also collated the information, gathering it up into a document or folder so it’s easier to find. Even a list of links to relevant specs, conversations, and the like is a good resource for later.
This time is also used to plan out the rest of these steps. What examples make sense to write? Which will make good tutorials? If a formal doc plan is required by my employer, this is when I write it. Even if one isn’t required, I usually outline the planned content to some extent at this point.
Step 2: Draft a rough version of the reference
If I’m responsible for writing the reference documentation (that is, the reference isn’t being automatically generated or written by someone else), I like to write the initial draft of the reference second. The goal at this stage is to simply build a skeleton of the reference with the basics and any obvious details. I find that drafting the reference is a great way to get a feel for what the API offers and how it works. I also get a better feeling for where the tricky bits are that may need extra attention in the text, or may benefit from additional sample code.
This is a good stage of the process to use AI. Asking your favorite AI to collate and generate a reference for the API can at least get the structure right, with proper prompting. This may benefit from an MCP service that can provide insight into your existing documentation, depending on your authoring environment and topic. Of course, the generated reference needs to be verified and reviewed for accuracy before you grant it any level of trust.
When something is unclear, I look at the source code. If that’s still unclear, I add my questions to a list I keep in an open document. Every few days, I email my latest batch of questions to the engineering team for their help. I don’t hit them with individual emails for every question (unless the question urgently needs an answer), and I don’t save up dozens of questions to ask all at once. Instead, I try to space them out to avoid overwhelming the engineers, which can result in the email sitting unanswered for a while until they have more time to deal with it.
As answers come in, I add them to my question and answer document, so I can refer to it anytime I need the information. And I don’t hesitate to ask follow-up questions, either directed toward the person that answered to the question or another member of the team that might provide a more complete picture that resolves my concerns.
At this stage, the reference contains special markers that indicate that I have outstanding questions, along the lines of “XXX>>> Find out what value there is to providing a non-default value for parameter Z” or “XXX>>> Is the following right?” The “XXX>>>” marker lets me search for these notes-to-self reliably and it stands out pretty well when scrolling or reading through the document. To be sure the markers are consistent throughout my documentation, I use a keyboard macro that automatically inserts them for me.
I use this rough draft of the reference as a tentative source of truth while I work on step 3 of my documentation process.
Step 3: Write one or more code examples
At this point, I start writing code. How much code I write depends on how complex the subject matter is and, critically, how much code I need to write and experiment with in order to feel confident that I understand the topic well enough to explain it to others.
If I’m confident from the outset that my understanding is sound (usually because the topic is small and relatively basic), I might not write any examples at all. Usually, though, I write at least one or two. For example, when documenting the Web Audio API for the Mozilla Developer Network (MDN), I wrote a relatively simple synth keyboard example. This doesn’t demonstrate the entirety of the API, but it covers the basics, and offers a good introduction to the API. Most importantly, it reassured me that I understood the fundamentals of the API well enough to write about it without making any serious errors that would be difficult to correct without rewrites.
In the case of WebRTC, on the other hand, I wrote a more comprehensive example that involved a WebSocket-based multi-user chat client with built-in support for one-on-one video chats. This let me be sure of myself when writing about the signaling process as well as other aspects of WebRTC’s API. As a bonus, I also got to use it as an example for WebSockets, which I also documented during this time.
This step offers another opportunity to use generative AI. You can ask it to build you an example meeting your needs, and you might get something useful back. A lot depends on how much source material is available for the LLM to go on when processing your prompt. If you’re documenting something genuinely new, access to the project source code may be needed if available. And even then, you may not get great results. As always, review and test the generated example carefully!
Step 4: Write a tutorial based on the code examples (if needed)
Next, if the API or technology is big or complex enough to justify it (or if an example is particularly engaging, or even if the technology is just fun to play with), I write a tutorial based on my favorite code examples. This should be an example that shows how to set up and use the API, and be either fairly simple or engaging and complete enough to be interesting. The tutorial describes what the example does and how it works, and the context of the example’s use case within the API I’m documenting.
The tutorial serves two purposes: first, it obviously helps teach the API’s users how to use it. Second, it helps reassure me further that I am correct about what the API does and how to use it, and it provides insight into my thinking that I can share with the engineering team for a technical review. Getting a tech review on the tutorial helps give me confidence that I’m on the right track and that I can complete the documentation without major misunderstandings.
Step 5: Complete the reference (if needed)
Again, assuming the reference is manually-written or that the writer has a way to contribute to the generated documentation, this is when I complete that work. I finish going through every section of the reference, completing anything that’s incomplete, replacing my marked questions and “to-do” markup with final text.
This step may involve further communication with the dev team, writing a little more code, or doing other research. One common task for this stage is to read the project source code to identify the errors that can be returned by each function, and, ideally what circumstances cause those errors to occur.
Step 6: Write the introduction and conceptual documentation
Now I’m ready to write the body of the developer guide content for the API. How much of this is needed depends on the topic, the complexity of the API, and the amount and size of the tutorial content that I’ve written. But there’s generally an introduction to the API, an overview of how it works and how to use it, and an explanation of any specialized terminology. The form this takes depends on the company’s style guide, of course.
You can use AI at this stage for anything from roughing out your draft to answering questions about specific terms or concepts.
Step 7: Add links
Now that the content is essentially complete, I can feel reasonably safe in going through the documentation adding any links that might have been left out during the initial authoring stages. This includes links back and forth between the reference and pages in the guide documentation and tutorials. These are often not done during earlier stages of the writing because the destination headings or anchors may not have existed yet.
For links into the reference from the guide content, I like to use a keyboard macro that asks for the symbol name, type, and any other information needed to generate a link to the target page. This macro then inserts a link for me, formatted appropriately based on the style guide.
Generally, I like to link to the reference for any symbol (such as a function, class, or type) the first time it’s used in an article. For long articles, I might do this more than once — possibly even once in every major section in which the symbol is used. If the presentation of the guide, such as on the web or in a documentation viewer in an IDE will automatically show reference material for symbols, I do this less often, but still try to do it at least once for any symbol used in my body text.
Step 8: Editorial review, copy edit, and cleanup
The final step is the editorial review and cleanup of the documentation. Ideally, at least one human reviewer reads the content and marks up changes that need to be made. If nobody is available, I do it myself (though this is less effective since I’m so close to the documentation). Then I copy edit, apply needed changes based on feedback, and make style adjustments based on the style guide if any are needed.
This is another stage where AI can be useful. Feed your style guide and any other style tips you have into the model and prompt it to review the document for clarity, accuracy, and so forth. Experiment with prompts to get one that works for your needs.
If the guide changes a lot during this time — and if time permits — I may request a second review and repeat the cleanup and editing process, as needed.