This document discusses various techniques for automating and improving technical documentation processes, including spelling checking with Hunspell and markdown-spellcheck, writing better with write-good and LanguageTool, adding screenshots with Robot Framework and Selenium, testing with APIs like Dredd and Sphinx, using Pandoc for multiformat output, and placeholders with sed. It encourages automating documentation work and testing to ensure documentation quality and usability.

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”

6. Spelling
Cathc those peski
typos like teh.

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

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

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

10. Write better
Learn to write
gooder

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

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

13. Write better - Next steps
• CI
• Editors

14. Screenshots
A picture says 1000
words

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

16. Screenshots - Next steps
• CI

17. Testing
What use is broken
code?

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

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

20. Code - Sphinx
sudo pip install Sphinx
make doctest

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

22. Bonus
material
Do we have time?

23. 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

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

25. 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

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

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

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