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 a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out my API documentation if you're looking for more info about that. If you're a technical writer and want to keep on top of the latest trends in the field, 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.
77/176 pages complete. Only 99 more pages to go.