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?
- -style guide
- -fuzzy language
- -filtering out swear words
- -could be for a single set
- -section stuff
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