Tackling technical debt in the docs

Delivered at Write the Docs Prague 2018.

In a world of legacy content, how do we resolve the issue of technical debt in our documentation?

As technical communicators, it’s very easy to get caught up in the cycle of moving from one release to another without taking time to refine what already exists. Trying to keep up with documenting new features means we often find ourselves navigating though outdated and disused stylesheets/labels/files/content/junk in projects that we inherited from technical communicators before us and haven’t had the time to clean up.

If this sounds familiar, then this presentation is for you!

It aims to help you tackle the daunting task of cleaning up your project and getting rid of technical debt once and for all. We will cover:

- What is technical debt, how does it accrue, and why should your organisation care
- How you can tackle your debt and give your documentation project the spring clean it needs
- Tips for staying debt‐free

Transcript

1. Tackling technical debt in the docs Louise Fahey | Technical Writer | @LouiseF_90
2. About me • Irish (but living in the UK) • Technical Writer • Big fan of Agile • Certified Scrum Master • Experience of green field projects and very messy projects
3. Agenda •What is technical debt? • What causes it? • Types and examples of technical debt •Signs you might be in debt •How to reduce your technical debt? •How to stay debt free in future?
4. What is technical debt?
5. Deferred necessary work
6. What causes technical debt in the docs?
7. Agile development cycles
8. Time pressure of being a lone documentarian
9. Project inheritance over “generations” of documentarians
10. Lack of: • Skills • Standards
11. Legacy content not removed from projects
12. Failure to modernize
13. Intentional and unintentional
14. Example 1 – Time constraints
15. Example 2 – Lack of standards and guidelines
16. Example 3 – Poor planning for the future
17. Example 4 – Lack of skills
18. Signs you are in debt • Slow project builds • Reports that show unused files • Localization issues • Comments like “we’ll come back and do it later” or “we can improve it in the next release”.
19. How to reduce your technical debt
21. Group your findings
22. Estimate the work involved in decreasing your debt
23. Prioritize your work
24. Share your findings
25. Piggy back if you can
26. Make time
27. Quantify the value of your work
28. How to stay debt free
29. Make time
30. Set standards
31. Make use of templates
33. Update your DoD
34. Add docs debt tasks to backlog
35. Top 3 things you can go back to work and target • Book a regular time slot in your calendar (initially to audit and then to stay on top of it) • Understand what your debt looks like and prioritize • Make other people understand the importance of resolving your debt
36. Thank you!