Difference between revisions of "People come and go"
From CitconWiki
Jump to navigationJump to search (Created page with "== People come and go - information transfer == * Default way: documentation * Documentation doesn't: too long, outdated, not true, etc. * Generated documentation ** Test nam...") |
(adding ideas mentioned in the discussion regarding the readability of test output) |
||
| Line 10: | Line 10: | ||
** unit tests | ** unit tests | ||
** BDD acceptance tests | ** BDD acceptance tests | ||
| + | * Output of executable documentation | ||
| + | ** mostly plain text (TestDox, AgileDox) or HTML | ||
| + | ** in certain cases it's worth generating visualizations based on tests (e.g. state transition diagrams) | ||
* Video documentation: screencasts for bug reports | * Video documentation: screencasts for bug reports | ||
* Searchable documentation | * Searchable documentation | ||
Revision as of 13:02, 23 October 2012
People come and go - information transfer
- Default way: documentation
- Documentation doesn't: too long, outdated, not true, etc.
- Generated documentation
- Test names
- Javadoc
- meta documentation: directory structure, etc.
- Executable documentation
- unit tests
- BDD acceptance tests
- Output of executable documentation
- mostly plain text (TestDox, AgileDox) or HTML
- in certain cases it's worth generating visualizations based on tests (e.g. state transition diagrams)
- Video documentation: screencasts for bug reports
- Searchable documentation
- Substitutes of documentation: face time, talk, e.g. before a new feature is being developed
- Documentation is not the goal. The goal is that the other person understands something
- Documentation needs to be searchable
- generated documentation too
- executable documentation too
- Put documentation to the right place:
- (links to) trouble-shooting tips to system monitor items
- docs should go to the same repo as code goes
- The book "Specification by example" was referenced http://specificationbyexample.com/
