Bit Rot in the Docs
8 likes2,360 views
The document discusses various causes of "bit rot" or technical documentation becoming outdated or inaccurate over time, such as changes to software or documentation platforms. It provides examples of remedies for bit rot like automated testing of code samples in documentation, conducting documentation reviews as part of the engineering process, collaborative testing sessions, and utilizing customer feedback. Remedies are recapped as automated testing, documentation reviews, spot-testing, and customer feedback.
Bit Rot in the Docs
- 1. Bit rot in the docs #docbitrot @sarahmaddox Bit rot in the docs
- 2. bit rot: n. Hypothetical disease the existence of which has been deduced from the observation that... Source: The Jargon File http://goo.gl/YTFTF4 #docbitrot @sarahmaddox Bit rot in the docs
- 3. unused programs or features will often stop working after sufficient time has passed, even if ‘nothing has changed’. Source: The Jargon File http://goo.gl/YTFTF4 #docbitrot @sarahmaddox Bit rot in the docs
- 4. Caused by cosmic rays? A notion long favored by hackers. #docbitrot @sarahmaddox Bit rot in the docs
- 5. Rooting out doc bit rot #docbitrot @sarahmaddox Bit rot in the docs Types Causes Remedies
- 6. Something’s rotten in the state of dem docs #docbitrot @sarahmaddox Bit rot in the docs Broken links Broken inclusions Outdated information Fiction Too much information
- 7. “...we found things in the docs that are no longer true, because we may have subtly changed the implementation without notifying the tech writers” #docbitrot @sarahmaddox Bit rot in the docs More about blitz tests: http://goo.gl/LnSXkV
- 8. Cosmic rays plus... Changes in environment Updates to documentation platform Last-minute changes in software Human error #docbitrot @sarahmaddox Bit rot in the docs
- 9. Cosmic rays plus... Changes in environment Updates to documentation platform Last-minute changes in software Human error #docbitrot @sarahmaddox Bit rot in the docs
- 10. Tinfoil hats plus... Automated testing of code samples Doc reviews in eng team procedures Spot-testing Customer feedback #docbitrot @sarahmaddox Bit rot in the docs
- 11. Automated testing of code samples Example: Simple Map http://goo.gl/ouVVfk Automated build system Real-time excerpts Benefits: ● Detect breakages in our samples ● Detect breaking changes in the API ● Be proactive with documentation updates #docbitrot @sarahmaddox Bit rot in the docs
- 12. Automated testing of code samples Example: Simple Map http://goo.gl/ouVVfk Automated build system Real-time excerpts Share tools Benefits: ● Detect breakages in our samples ● Detect breaking changes in the API ● Be proactive with documentation updates #docbitrot @sarahmaddox Bit rot in the docs
- 13. Doc reviews in eng team procedures Definition of done http://goo.gl/dT5zF1 Share the same issue tracker Share the same review tool Take part in code reviews #docbitrot @sarahmaddox Bit rot in the docs
- 14. Collaborative spot testing A coordinated testing session Interested parties testing specific functionality Testing code and documentation together Works well for: ● Major update ● Change affecting many API methods ● Feature worked on by more than one engineer ● Work spread over a long period #docbitrot @sarahmaddox Bit rot in the docs
- 15. Collaborative spot testing #docbitrot @sarahmaddox Bit rot in the docs
- 16. Customer feedback #docbitrot @sarahmaddox Bit rot in the docs Harnessing the audience ● Feedback on the documentation ● Comments on blog posts ● Twitter ● Google+ ● Stack Overflow ● User forums
- 17. #docbitrot @sarahmaddox Bit rot in the docs Doc comments Doc addition/correction Support request Help request Product feature/improvement Praise Other
- 18. #docbitrot @sarahmaddox Bit rot in the docs Feedback Tools External ● Disqus ● Wufoo ● Qualaroo Integrated ○ Confluence ○ MindTouch
- 19. Recap of bit rot remedies Automated testing of code samples Doc reviews in eng team procedures Spot-testing Customer feedback #docbitrot @sarahmaddox Bit rot in the docs
- 20. Recap of bit rot remedies Automated testing of code samples Doc reviews in eng team procedures Spot-testing Customer feedback #docbitrot @sarahmaddox Bit rot in the docs Blitz tests (freebie)
- 21. Twitter @sarahmaddox Google+ +sarahmaddox Email [email protected] Slideshare sarahmaddox Blog ffeathers.wordpress.com #docbitrot @sarahmaddox Bit rot in the docs Contacting me