Sarah Day - What You Get When You Invest Non-docs Time in Docs Tools

Sarah Day

Senior Technical Writer at LaunchDarkly

Sarah's presentation (video recording)

Sarah's slides

"I think there's kind of an inflection point in a lot of technical writers's careers, especially if they're sole contributors to their company, where they have to stop thinking about the documentation set that they work with and start thinking about how to incorporate their role and technical writing in the larger ecosystem of the company. I had kind of a crash course in doing that at LaunchDarkly when we redesigned our documentation website."

Developer tools need accurate, reliable, usable documentation to appeal to a wide range of users.

Documentation websites:

• A new developer tool's first point of contact.
• In the beginning probably functional but not really useful.
• Good content and strong writing may be obscured by poor search appliance, lackluster design, and inscrutable feedback forms.

How to implement big changes to documentation sets and company behavior?

Template to make decision

Create a practical, actionable plan to achieve the changes.

1. Map the workflows

   • teams' relationships to the larger organization
   • model for scope-design-build process
   • get leadership & organizational support for implementing changes
   • docs within engineering department (rather than in support)
   • plan for the extra workload
   • clear goal, scope accurately
   • weigh impact and challenges of different parts of the project: where to invest early efforts
     
     

2. Define objectives

   • what do you want exactly
   • how will you measure the impact
   • is it only the docs team involved, where else do you need input from
   • consider trade-off between impact on others and their time invested
   • what is the bare minimum of functionality, the absolute minimum set of success criteria
   • early design- and engineering goal
   • have a holistic vision in mind that you can change with the technical realities
     
     

3. Build the team

   • what roles do you absolutely need to make it a success
   • marketing to help inform others on changes
   • devops because it is always more complicated than it looks from the outside
   • who gives advice and feedback - opinionated stakeholders and interested third parties advocating towards leadership
   • help with testing and troubleshooting
   • will you need to learn new skills
     
     

4. Execute

   • cut at least 25% of your original scope
   • focus on the roadmap
   • strategy for staying connected and communicating
   • plan for misschaps, put redundancies in place, add time buffer
   • scheduled status updates to all stakeholders
   • regular demos for buy-in and feedback from key stakeholders
   • wide testing and feedback collection internally before release
   • important feedback but out of scope: shelf it for later
     
     

5. Land and expand

   • measure success, keep tracking performance
   • can other teams reuse what you built
   • feedback from customers, and from internal non-docs and non-engineering stakeholders
   • maintenance: continuous internal and community input
   • make the content an ongoing process of discussion and feedback
   • prioritize UX and design change suggestions: must fix, nice to have, won't fix
   • who is formally responsible for fixing arising issues: services ownership