Skip to content

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.