Post on 14-Jun-2015
description
transcript
Bit rot in the docs#docbitrot @sarahmaddox
Bit rot in the docs
Bit rot in the docs#docbitrot @sarahmaddox
bit rot: n. Hypothetical disease the existence of which has been deduced from the observation that... Source: The Jargon File
http://goo.gl/YTFTF4
Bit rot in the docs#docbitrot @sarahmaddox
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
Bit rot in the docs#docbitrot @sarahmaddox
Caused by cosmic rays? A notion long favored by hackers.
Bit rot in the docs#docbitrot @sarahmaddox
Rooting out doc bit rot
Types
Causes
Remedies
Bit rot in the docs#docbitrot @sarahmaddox
Something’s rotten in the state of dem docs
Broken linksBroken inclusionsOutdated informationFictionToo much information
Bit rot in the docs#docbitrot @sarahmaddox
“...we found things in the docs that are no longer true, because we may have subtly changed the implementation without notifying the tech writers”
More about blitz tests:http://goo.gl/LnSXkV
Bit rot in the docs#docbitrot @sarahmaddox
Cosmic rays plus...
Changes in environmentUpdates to documentation platformLast-minute changes in softwareHuman error
Bit rot in the docs#docbitrot @sarahmaddox
Cosmic rays plus...
Changes in environmentUpdates to documentation platformLast-minute changes in softwareHuman error
Bit rot in the docs#docbitrot @sarahmaddox
Tinfoil hats plus...
Automated testing of code samplesDoc reviews in eng team proceduresSpot-testingCustomer feedback
Bit rot in the docs#docbitrot @sarahmaddox
Automated testing of code samples
Example: Simple Map http://goo.gl/ouVVfk Automated build systemReal-time excerpts
Benefits:● Detect breakages in our samples● Detect breaking changes in the API● Be proactive with documentation updates
Bit rot in the docs#docbitrot @sarahmaddox
Automated testing of code samples
Example: Simple Map http://goo.gl/ouVVfk Automated build systemReal-time excerpts
Benefits:● Detect breakages in our samples● Detect breaking changes in the API● Be proactive with documentation updates
Share tools
Bit rot in the docs#docbitrot @sarahmaddox
Doc reviews in eng team procedures
Definition of done http://goo.gl/dT5zF1 Share the same issue trackerShare the same review toolTake part in code reviews
Bit rot in the docs#docbitrot @sarahmaddox
Collaborative spot testing
A coordinated testing session Interested parties testing specific functionalityTesting 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
Bit rot in the docs#docbitrot @sarahmaddox
Collaborative spot testing
Bit rot in the docs#docbitrot @sarahmaddox
Customer feedback
Harnessing the audience
● Feedback on the documentation● Comments on blog posts● Twitter● Google+● Stack Overflow● User forums
Bit rot in the docs#docbitrot @sarahmaddox
Doc comments
Doc addition/correction
Support request
Help request
Product feature/improvement
Praise
Other
Bit rot in the docs#docbitrot @sarahmaddox
Feedback Tools
External● Disqus● Wufoo● Qualaroo
Integrated○ Confluence○ MindTouch
Bit rot in the docs#docbitrot @sarahmaddox
Recap of bit rot remedies
Automated testing of code samplesDoc reviews in eng team proceduresSpot-testingCustomer feedback
Bit rot in the docs#docbitrot @sarahmaddox
Recap of bit rot remedies
Automated testing of code samplesDoc reviews in eng team proceduresSpot-testingCustomer feedback
Blitz tests (freebie)
Bit rot in the docs#docbitrot @sarahmaddox
Twitter @sarahmaddox
Google+ +sarahmaddox
Email sarahmaddox@google.com
Slideshare sarahmaddox
Blog ffeathers.wordpress.com
Contacting me