Recommended
More Related Content
What's hot
What's hot (20)
Similar to Tested and Correct, How to Make Sure Your Documentation Keeps Working
Similar to Tested and Correct, How to Make Sure Your Documentation Keeps Working (20)
Recently uploaded
Recently uploaded (20)
Tested and Correct, How to Make Sure Your Documentation Keeps Working
- 1. tested and correct how to make sure your documentation keeps working
- 2. adam dangoor software developer at clusterhq adamdangoor@gmail.com @adamdangoor https://github.com/adamtheturtle
- 3. the plan
- 4. the problem
- 5. the problem
- 6. the problem
- 7. the problem
- 9. the traditional way • memory • •
- 10. the traditional way • memory • periodic review •
- 11. the traditional way • memory • periodic review • user feedback
- 12. why this is terrible • software interacts with other software which changes without warning • • •
- 13. why this is terrible • software interacts with other software which changes without warning • memory is imperfect • •
- 14. why this is terrible • software interacts with other software which changes without warning • memory is imperfect • we have better things to do •
- 15. why this is terrible • software interacts with other software which changes without warning • memory is imperfect • we have better things to do • user feedback is not guaranteed
- 16. a better way
- 17. software testing
- 20. that is just the start
- 21. flocker install instructions .. code-block:: console alice@mercury:~$ brew tap ClusterHQ/tap ... alice@mercury:~$ brew install flocker-1.2.0 ... alice@mercury:~$ brew test flocker-1.2.0 ... alice@mercury:~$
- 22. if change is hard, we stagnate
- 23. flocker install instructions (part two) .. task:: test_homebrew flocker-|latest-installable| :prompt: alice@mercury:~$ def task_test_homebrew(recipe): return sequence([ run_from_args(['brew', 'tap', 'ClusterHQ/tap']), run("brew update"), run("brew install {recipe}".format(recipe=recipe)), run("brew test {recipe}".format(recipe=recipe)), ])
- 24. command line output just use wordish https://pypi.python.org/pypi/wordish
- 25. changing the organisational model “organizations which design systems ... are constrained to produce designs which are copies of the communication structures of these organizations” –melvin conway
- 26. code then document code and document
- 27. what to do about it
- 29. generating documentation sphinx.ext.autodoc class Word(object): """ A string which can be represented by a list of strings which are each valid tiles. """
- 32. generating documentation selenium ~/Documents/boggle-solver/docs$ git diff diff --git a/docs/results.html b/docs/results.html index 776e5e0..7fff02c 100644 --- a/docs/results.html +++ b/docs/results.html @@ -2,7 +2,7 @@ <head> <style> .results { - background-color: #b0c4de; + background-color: green; font-family: helvetica; } </style>
- 34. summary
- 36. hold on a minute
- 37. close, but no {cigar, ai}
- 39. other benefits
- 40. thank you for listening