1.
Automate your Docs,
automate yourself
Yes… Test your Docs 😁
FOSDEM 2017
@chrischinch

2.
What’s one of the first
things you look at
with a new project?

3.
–Ken Williams, Perl
“Documentation is
complete when
someone can use your
project without having
to look at its code”

4.
–Andy Mabbett, Wikimedia
“Documentation is like
housework”

5.
Spelling
Cathc those peski
typos like teh.

6.
Hunspell
sudo apt-get install hunspell
brew install hunspell
# Add dictionaries
hunspell -u3 -H -d en_US **/*.md

7.
markdown-spellcheck
npm install markdown-spellcheck -g
mdspell -r -n -a --en-us **/*.md

8.
Spelling - Next steps
• Custom dictionary
• suares.com/index.php?page_id=25&news_id=233
• CI
• Editors
• Other file types

9.
Write better
Learn to write
gooder

10.
write-good
npm install write-good -g
write-good **/*.md
write-good **/*.md --weasel --so
write-good **/*.md --no-passive

11.
LanguageTool
java -jar /Users/chrisward/Workspace/
LanguageTool-3.6/languagetool-
commandline.jar -l en-US "index.md"

12.
Write better - Next steps
• CI
• Editors

13.
Screenshots
A picture says 1000
words

14.
Robot framework
# Install PhantomJS
easy_install robotframework
robotframework-selenium2library image
robotframework-selenium2screenshots
robot folder

15.
Screenshots - Next steps
• CI

16.
Testing
What use is broken
code?

17.
APIs - dredd
npm install dredd
dredd out/cda.apib https://
cdn.contentful.com --hookfiles=./
test-hooks.js

18.
Other options
• Jetman - Write tests in JavaScript
• Postman + Newman - Tests with desktop
app
• Myriad commercial options

19.
Code - Sphinx
sudo pip install Sphinx
make doctest

20.
Testing - Next steps
• non-Python?
• CI

21.
Bonus
material
Do we have time?

22.
Multiformat - Pandoc
for filename in **/*.md; do
pandoc --from=markdown+yaml_metadata_block --
smart -o "$(basename "$filename" .md)".pdf --
latex-engine=xelatex $filename
pandoc --from=markdown+yaml_metadata_block --
smart -o "$(basename "$filename" .md)".html --
latex-engine=xelatex $filename
done

23.
Editor snippets
• Atom: Built in
• Vim: ultisnips, snipmate, xtemplate and
more
• Emacs: Yasnippet
• Sublime: Built in

24.
Placeholders - sed
if [[ $2 == "preview" ]]; then
sed -i -e 's/<access_token>/
46cc338e0d4647e3b9f98c52615a2414d725b6ddffdbbb2
f3bed26f73789dd53/g' $result_string
else
sed -i -e 's/<access_token>/
297e67b247c1a77c1a23bb33bf4c32b81500519edd767a8
384a4b8f8803fb971/g' $result_string
fi

25.
Want More?
• bit.ly/2dXs5nr
• coala.io
• testthedocs.org
• slack.writethedocs.org

26.
–Me (maybe)
“Documentation
isn’t just for
developers”

27.
Thank You!
Chris Ward
contentful.com
gregariousmammal.com
@chrischinch
I have stickers and merchandise!