Chapter 8: Code tutorials
Documenting code can be one of the most challenging aspects of API documentation, especially for non-engineers. Code can be hard to document because of its non-linear nature. For example,you don’t simply start by describing chunks of code from top to bottom. Figuring out your audience’s technical level can also be a guessing game, as a user’s proficiency in one language or area might not carry over to another. As you document code, focus on the “why” instead of the “how,” and consider building up complexity in stages, starting simple and expanding into more advanced use cases. If you can provide interactive browser experiences with code, which allows users to adjust the input and immediately see the output, this can also help developers learn.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.
79/167 pages complete. Only 88 more pages to go.