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