Write better documentation with testing
Introduction
Documentation is “How a product is expected to be used” and needs to be accurate, understandable, and up-to-date.
Documentation that is:
- Accurate can become long and cryptic (bad for understanding and updating)
- Often updated, can become fluffy and fragmented (bad for accuracy and understanding)
- Understandable can become long and shallow (bad updating and or accuracy)
So how to do it? By using Given, When, Then!
Make it Understandable
Lego and IKEA have some of the best manuals / documentation, because they write them as test cases using “Given, When, Then”:
Given – don’t start building without these elements.
When – what actions you are required to do (and in what order)
Then – what you should expect of the end result.
Documentation written this way is easy to understand.
Make it Accurate
“Given, When, Then” is a test case to describe product behavior (read: Definition of a test case)
A good test case describes only a single product behavior, which makes it accurate. A bad test case will describe multiple behaviors at once and be confusing.
A set of good test cases is called a test suite, and will describe a set of behaviors called a feature.
Documentation written this way is accurate.
Make it Always up-to-date
Documentation written as test cases, makes the documentation testable.
Given the product has changed. When the test cases and pass, then the documentation is up-to-date:
- given the product has changed
- when some test cases (documentation) fail,
- then the test cases (documentation) needs to be updated.
Documentation written this way
is called “Living Documentation”,
because it is always up-to-date.
About The Author
