Source code review skill
One of the best things you can do working in API documentation is get more involved in reviewing source code comments that developers are submitting. Because the comments in source code files (such as java, proto, or other files) become the reference documentation in your docs, it’s important that you have a hand in reviewing, editing, and shaping this content. Too many tech writers abdicate their roles when it comes to source code content because the format and conventions might seem a bit unfamiliar. However, this content becomes part of your docs and reflects your content. You’ll be in charge of this content, so don’t rely on engineers to own it.
There are several steps for getting a handle on source code comments using skills.
- Add yourself as a Cc to any changelists that engineers make in the code repositories you support.
- When a changelist comes in, run your skill against it.
-
Review the comments provided and consider any adjustments.
- Add yourself as a Cc to any changelists that engineers make in the code repositories you support.
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.