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.
%+27788225528 love spells in Colorado Springs Psychic Readings, Attraction sp...
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
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 sarahmaddox@google.com
Slideshare sarahmaddox
Blog ffeathers.wordpress.com
#docbitrot @sarahmaddox Bit rot in the docs
Contacting me