Vilnius 2019 notes - Legacy docs

Write the Docs Vilnius 2019 saw some excellent talks. Somewhat belatedly, I'm writing up my notes. Here's the fourth.

Speaker: Elina McCafferty

Fixing legacy docs without burning out

Elina spoke about her experience taking on a massive body of legacy documentation.

Challenges:

• Outdated tone and focus
• Overwhelming content
• Quality issues
• Fragmentation
• Tool sprawl

The goal? Lean modern content. This is a multi-year project.

More challenges:

• Keeping up with new dev
• Prioritisation
• Getting a clear overview of a large to-do list

Steps:

1. Collect data to identify where you need to focus:
   • User research
   • Analytics
   • Support
   • Community docs
2. Principles:
   • First impressions count: make sure the first thing users see is good.
   • The 80/20 rule, so focus on the 20% of your docs with the largest impact.
3. Fix the following:
   • Your top level nodes (improves first impressions, including potential sales)
   • Your top 20 topics.
   • Titles, introductions, structure - even if you don't have time to touch the content right now.
4. Sustaining yourself over a multi-year project:
   • To-do lists keep you focused.
   • Be realistic about your timeframes.
   • Have an explicit plan.
   • Be prepared to dip in and out of work on the legacy docs. New docs will pull you away.
   • Have a quick fix list and a big fix list (and perhaps more finegrained categories)
   • Use Agile to your advantage - what is "good enough"?
   • You may not get any feedback. Instead, look for a decrease in complaints.