Docs for Developers: An Engineer's Field Guide to Technical Writing

Huge savings for students

Each student receives a 50% discount off of most books in the HSG Book Store. During class, please ask the instructor about purchase details.
List Price: $39.99
Price: $20.00
You Save: $20.00
5
  1. Getting Started

  2. Researching documentation

    1. Understanding your users

    2. Cultivating empathy

    3. Understanding user desires, user needs, and company needs

    4. Recruiting users for research

  3. Research methods

    1. Reading code comments

    2. Trying it out

    3. Friction logs

    4. Running diverse and inclusive focus groups and interviews

    5. User journey mapping

  4. Identifying and working with stakeholders

    1. Finding your experts

    2. Collaborative documentation development

  5. Learning from existing content

    1. The value of design documents

    2. Finding examples in industry

  • Designing documentation

    1. Defining your initial set of content

    2. Deciding your minimum viable documentation

    3. Drafting test and acceptance criteria

  • Understanding content types

  • Concepts, tutorials and reference documentation

  • Code comments

  • API specifications

  • READMEs

  • Guides

  • Release notes

  • Drafting documentation

    1. Setting yourself up for writing success

    2. Who is this for? Personas, requirements, content types

    3. Definition of done

    4. How to iterate

    Tools and tips for writing rough drafts

    1. Understanding your needs

    2. Choosing your writing tools (handwriting, text-only, productivity/measurement writing tools)

    3. "Hacks" to get started drafting content

  • Mechanics

  • Headings

  • Paragraphs

  • Lists

  • Notes and warnings

  • Conclusions/tests

  • Using templates to form drafts

    1. Purpose of a template

    2. How to derive a template from existing docs

    3. How to take templates into text

  • Gathering initial feedback

  • Feedback methods

  • Integrating feedback

  • Getting feedback from difficult contributors

  • Editing content for publication

    1. Determine destination

    2. Editing tools (Grammarly, linters, etc)

    3. Declaring good enough

  • Recap, strategies, and reassurance

  • Structuring sets of documentation

    1. Where content types live

    2. Concepts, tutorials and reference documentation

    3. Code comments

    4. API specifications

    5. READMEs

    6. Guides

    7. Release notes

  • Designing your information architecture

    1. Content information architecture styles

    2. Designing for search

    3. Creating clear, well-lit paths through content

  • User testing and maintenance

  • Planning for document automation

  • Integrating code samples and visual content

    1. Integrating code samples

    2. When and why to use code samples

    3. Creating concise, usable, maintainable samples

    4. Standardising your samples

  • Using visual content: Screenshots, diagrams, and videos

    1. When your documentation may need visual content

    2. Making your visual content accessible

    3. Integrating screenshots, diagrams

    4. Videos

  • Measuring documentation success

  • How documentation succeeds

  • Measuring different types of documentation quality

    1. Structural Quality

    2. Functional Quality

    3. Process Quality

  • Measuring what you want to change

  • Drawing conclusio

    Apress