Episode 501: Bob Ducharme on Creating Technical Documentation for Software Projects

Writing Essentials

Bob Ducharme emphasizes the importance of understanding technical jargon and differentiating it from buzzwords in technical writing. He explains that having a background in computer science can be beneficial, especially when communicating with developers and translating complex concepts for non-technical users. Bob shares, "Having a master's in computer science helps me to talk to the PhDs and then translate what they're saying to regular people." This skill is crucial for creating user-facing documentation that is both accurate and accessible 1.

   

Role of Writer

The role of a technical writer is pivotal in bridging the gap between developers and end-users. Bob Ducharme highlights that while developers excel in coding, they may struggle to convey product usage to new users. He states, "The tech writer is the person who explains how to use it," underscoring the necessity of clear communication skills to translate technical details into user-friendly guides 2. This involves not only writing manuals but also engaging with developers to clarify technical aspects.

   

Documentation Techniques

Effective documentation requires organizing information in a way that is easy for users to navigate. Bob Ducharme discusses the importance of structuring user guides around tasks rather than technical jargon, making it easier for users to find the information they need. He notes, "A user guide is really aimed at someone who doesn't know the product," emphasizing the need for clarity and accessibility 3. Additionally, Bob advises using bulleted lists over numbered lists when order isn't essential, to enhance readability and user engagement 4.