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:
- Collect data to identify where you need to focus:
- User research
- Analytics
- Support
- Community docs
- 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.
- 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.
- 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.