This is a read only archive of pad.okfn.org. See the shutdown announcement for details.

writethedocs-testing-qa
from https://www.evernote.com/shard/s143/sh/ff22a462-9250-4ad0-8a9f-348d3e544a79/321d430361b5d7a8f0f6391bc27a8679
by https://twitter.com/kvantomme @kvantomme

how automate
how user test

what are the health indicators, 
how does it scale

last edit date, if not 2yrs - probably outdated
flag for review

what is useful what not
user testing?
bounce rate, rating
helpfulness rating

what can you measure automatically

test code that is in the docs - if still works with current release, evaluate code samples
"are documented” on MDN
docs outdated fast
flag bugs in software that affect docs

info from bug tracker systems
size of scope?
health indicators, bugs, technical reviews, etc.
tweets with documentation URL
likes, vs complaining

robotframework - used in Plone - video https://www.youtube.com/watch?v=87G4QiIqQCY
done through sphinx
on top of selenium

tests for documentation 
e.g. page structure
what do you want to test for?
create auto testing tool
using regex for testing
add-on sdk

for community, are we documented yet
here you can help…
in DITA you can enforce all sorts of structure
allows for drive by edits

where do you write - in text editor, browser?
git pre-commit hook, docs - always pull request
collecting tools - how to test docs

force people to revisit later?

updating docs after release of software
decoupled release cycle
update docs faster

mark docs
only show latest branch for docs, 
conditional text
-issues with conditional text
older ones have more search weight, so they show up more
can still cause problems 

docs should move faster than code
problem with old pdfs
built-in documentation in the website
big linux - single page html, chaptered html, pdf and epub
try to simplify - wanted just html, several customers really need pdf
people do print docs

swagger
sphinx - can define calls and get posts of the API
calls are next to the documentation

Behat BDD
tests packaged with the docs
doctest - code then docs

with sphinx, 
do docs, then also test those paragraphs

BDD as a tool to make sure user story becomes a itel test



automated QA on docs
big linux - check broken links, and package names
typos
how long is the description 
length of sentences
best practices for what a docs page looks like
e.g. length of whole article
structure of an article
headlines present?
what are the quality checkpoints you should check for

DITA plugin - has rules, that is not about DITA itself
language, types of words
flesh kincaid readability test
hemingway app uses flesh kincaid
DITA QA plugin


nighly node.js that runs through - does metrics

bash scripts that go over sources, done in jenkins
on every commit, builds book and runs scripts