last talk of the day is the fantastic Manny Silva talking documentation testing strategy.
"Something always breaks."
Documentation ends up out of sync, because changes don't get communicated downstream. This creates distrust internally and user distrust. #WTD
"Something always breaks."
Documentation ends up out of sync, because changes don't get communicated downstream. This creates distrust internally and user distrust. #WTD
Comments
Docs testing is often manual.
He's right. I just spent the last week updating stuff that was wrong. All relatively minor but..
"If you don't test your docs, your users will."
TRUTH. If you're lucky, it's 'only' your CS folks.
Every thing we write about, every procedure is a test. "Click Save." - how often is that in a doc? ALLLLLLLL THE TIIIIIIME.
This is a thing *we* can test.
Maintaining screenshots is terrible, but if you have a testable procedure... it captures a new screenshot. And potentially even *update the screenshot*.
Bonkers, right?
docs testing tools are generally made for engineers.
Manny made Doc Detective for writers. Other engines have other focuses.
Validation is also a thing that's ... let's say that's less common. A lot of docs folks (in my experience, again) don't tend to get the code samples and we make guesses. Sometimes we're wrong.
Writers. They have writers. Sometimes.
"Docs as tests" adds automated testing and development practices. #testthedocs #writethedocs
Docs as tests are NOT linting, link checks, format, or style checking. These -are- important, and you should use these tools.