Se ha denunciado esta presentación.
Utilizamos tu perfil de LinkedIn y tus datos de actividad para personalizar los anuncios y mostrarte publicidad más relevante. Puedes cambiar tus preferencias de publicidad en cualquier momento.
Automate your Docs, automate yourself Yes… Test your Docs 😁 FOSDEM 2017
 @chrischinch
What’s one of the first things you look at with a new project?
–Ken Williams, Perl “Documentation is complete when someone can use your project without having to look at its code”
–Andy Mabbett, Wikimedia “Documentation is like housework”
Spelling Cathc those peski typos like teh.
Hunspell sudo apt-get install hunspell brew install hunspell # Add dictionaries hunspell -u3 -H -d en_US **/*.md
markdown-spellcheck npm install markdown-spellcheck -g mdspell -r -n -a --en-us **/*.md
Spelling - Next steps • Custom dictionary • suares.com/index.php?page_id=25&news_id=233 • CI • Editors • Other file types
Write better Learn to write gooder
write-good npm install write-good -g write-good **/*.md write-good **/*.md --weasel --so write-good **/*.md --no-passive
LanguageTool java -jar /Users/chrisward/Workspace/ LanguageTool-3.6/languagetool- commandline.jar -l en-US "index.md"
Write better - Next steps • CI • Editors
Screenshots A picture says 1000 words
Robot framework # Install PhantomJS easy_install robotframework robotframework-selenium2library image robotframework-selen...
Screenshots - Next steps • CI
Testing What use is broken code?
APIs - dredd npm install dredd dredd out/cda.apib https:// cdn.contentful.com --hookfiles=./ test-hooks.js
Other options • Jetman - Write tests in JavaScript • Postman + Newman - Tests with desktop app • Myriad commercial options
Code - Sphinx sudo pip install Sphinx make doctest
Testing - Next steps • non-Python? • CI
Bonus material Do we have time?
Multiformat - Pandoc for filename in **/*.md; do pandoc --from=markdown+yaml_metadata_block -- smart -o "$(basename "$file...
Editor snippets • Atom: Built in • Vim: ultisnips, snipmate, xtemplate and more • Emacs: Yasnippet • Sublime: Built in
Placeholders - sed if [[ $2 == "preview" ]]; then sed -i -e 's/<access_token>/ 46cc338e0d4647e3b9f98c52615a2414d725b6ddffd...
Want More? • bit.ly/2dXs5nr • coala.io • testthedocs.org • slack.writethedocs.org
–Me (maybe) “Documentation isn’t just for developers”
Thank You! Chris Ward contentful.com gregariousmammal.com @chrischinch I have stickers and merchandise!
Automate your docs, automate yourself
Próxima SlideShare
Cargando en…5
×

Automate your docs, automate yourself

235 visualizaciones

Publicado el

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.

Publicado en: Tecnología
Licencia: CC Attribution License
no profile picture user

  • Inicia sesión para ver los comentarios

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!

×