Good Documentation is Hard

🌈 Abstract

The article discusses the challenges and responsibilities of being a technical writer, including:

• The unexpected realities of the job, such as having to document existing content rather than just writing new material
• The need to understand complex technical concepts and work closely with engineers and developers to accurately document their work
• The importance of considering the diverse needs and backgrounds of the audience when creating documentation
• The ongoing effort required to maintain and improve documentation over time, even as the underlying software and features continue to evolve

🙋 Q&A

[01] The Unexpected Realities of Being a Technical Writer

1. What were some of the unexpected realities the author faced as a technical writer?

• The author found that there were already many unwritten blurbs and outdated content that needed to be updated, rather than just writing new material as expected
• The author sometimes didn't understand the technical concepts well enough to write useful documentation, and had to spend time with support tickets or interviewing the developers
• The author had to be careful not to make too many changes to existing documentation, as it had been carefully crafted over time

2. How did the author approach documenting new features and updates?

• The author would write missing blurbs, update old ones, and get new documentation out just in time for releases
• When the author understood the new features well enough, writing and publishing the documentation wasn't too difficult since there was already an established publishing workflow

3. What other tasks did the author take on beyond just writing documentation?

• The author worked on improving the documentation process, such as automating tasks and making the documentation feel more consistent with the website and web app
• The author also incorporated feedback and ideas from other people, even those not officially involved in the documentation process

[02] The Challenges of Technical Writing

1. What are some of the key challenges the author identifies in being a technical writer?

• Documenting one's own work is easier, as the author already understands the problem and solution
• Documenting someone else's work requires more effort, as the author needs to understand the work by asking questions and keeping up with the release schedule
• The author had to balance providing enough time to write quality documentation while not letting the underlying work change too much during that time

2. How does the author describe the role of a technical writer in relation to the software development process?

• The author uses a metaphor of building roads and bridges to help people navigate the "landscape" of the software, rather than just hacking through the wilderness
• The technical writer needs to anticipate where people will want to go and build the appropriate paths and signage, even as the landscape continues to evolve

3. What does the author suggest is important for effective technical writing beyond just the writing itself?

• The author emphasizes the need for clarity, coordination, and intention across the entire organization, not just from the technical writer
• A commitment to writing and championing its importance within the company culture can also greatly benefit the documentation efforts