Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Automate your docs, automate yourself

141 views

Published on

I'm back at the infamous FOSDEM, this time to talk about making your documentation polished by automating spelling, grammar, testing, screenshots and so much more.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Automate your docs, automate yourself

  1. 1. Automate your Docs, automate yourself Yes… Test your Docs 😁 FOSDEM 2017
 @chrischinch
  2. 2. What’s one of the first things you look at with a new project?
  3. 3. –Ken Williams, Perl “Documentation is complete when someone can use your project without having to look at its code”
  4. 4. –Andy Mabbett, Wikimedia “Documentation is like housework”
  5. 5. Spelling Cathc those peski typos like teh.
  6. 6. Hunspell sudo apt-get install hunspell brew install hunspell # Add dictionaries hunspell -u3 -H -d en_US **/*.md
  7. 7. markdown-spellcheck npm install markdown-spellcheck -g mdspell -r -n -a --en-us **/*.md
  8. 8. Spelling - Next steps • Custom dictionary • suares.com/index.php?page_id=25&news_id=233 • CI • Editors • Other file types
  9. 9. Write better Learn to write gooder
  10. 10. write-good npm install write-good -g write-good **/*.md write-good **/*.md --weasel --so write-good **/*.md --no-passive
  11. 11. LanguageTool java -jar /Users/chrisward/Workspace/ LanguageTool-3.6/languagetool- commandline.jar -l en-US "index.md"
  12. 12. Write better - Next steps • CI • Editors
  13. 13. Screenshots A picture says 1000 words
  14. 14. Robot framework # Install PhantomJS easy_install robotframework robotframework-selenium2library image robotframework-selenium2screenshots robot folder
  15. 15. Screenshots - Next steps • CI
  16. 16. Testing What use is broken code?
  17. 17. APIs - dredd npm install dredd dredd out/cda.apib https:// cdn.contentful.com --hookfiles=./ test-hooks.js
  18. 18. Other options • Jetman - Write tests in JavaScript • Postman + Newman - Tests with desktop app • Myriad commercial options
  19. 19. Code - Sphinx sudo pip install Sphinx make doctest
  20. 20. Testing - Next steps • non-Python? • CI
  21. 21. Bonus material Do we have time?
  22. 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. 23. Editor snippets • Atom: Built in • Vim: ultisnips, snipmate, xtemplate and more • Emacs: Yasnippet • Sublime: Built in
  24. 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. 25. Want More? • bit.ly/2dXs5nr • coala.io • testthedocs.org • slack.writethedocs.org
  26. 26. –Me (maybe) “Documentation isn’t just for developers”
  27. 27. Thank You! Chris Ward contentful.com gregariousmammal.com @chrischinch I have stickers and merchandise!

×