Skip to content

Vilnius 2019 notes: Legacy docs

Notes from the legacy docs conference talk at Write the Docs Vilnius 2019.

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.