Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,000+ subscribers

Stitcher radio

Search results

Upcoming event:
I'm giving an API documentation workshop in Los Angeles, California, on January 23, 2020. Check it out on EventBrite and register today to receive a $100 early bird discount.

New topic in API course: Why documenting code is so difficult

by Tom Johnson on Jul 29, 2019 • 0 Comments
categories: api-doc

I recently added a new section in my API documentation course on documenting code. This is an entire section that I'm building out with about 7-8 topics. The introduction is called Why documenting code is so difficult.

Here’s the intro:

Software code, often written in Java, C++, or any other language, is challenging to document in part because technical writers often aren’t already fluent in the programming language. But even for writers or developers who are fluent in the language, code is hard to document. There isn’t a step-by-step process to follow. Code is often arranged in non-linear order, so you can’t simply proceed line-by-line through it. There’s also the question of how much to document, what to cover, and where to include the documentation. Overall, best practices for documenting code are somewhat fuzzy and undefined, which makes documenting code one of the most challenging and difficult tasks technical writers face.

Read more here: Why documenting code is so difficult.

follow us in feedly