Use Notepad, not Word when you start writing your plans
Following up on the last post on starting with a blank sheet of paper, Rick Grey pointed out that when he first starts writing up his notes, he prefers to work in a plain text editor - not a word processor. He does this so his focus remains on content, not on formatting. If he doesn't have tables, bullets, and headings available to him then he can't spend hours trying to format them to get them just right.
This tip was part of a brainstorm developed at the September 2011 Indianapolis Workshop on Software Testing on the topic of "Documenting for Testing." The attendees of that workshop (and participants in the brainstorm) included: Charlie Audritsh, Scott Barber, Rick Grey, Michael Kelly, Natalie Mego, Charles Penn, Margie Weaver, and Tina Zaza.
Start with a blank sheet of paper
When I sit down to write a formal test document, I start with a blank sheet of paper. I do not start with a template.
I do that for a couple of reasons. First, I find that when I use a template I spend more time focusing on filling in the various sections than I do really thinking about the problem I'm trying to solve. The template distracts me from focusing on the problem in a deep and meaningful way. Second, I find that templates can anchor my thinking into specific solutions. When I'm actively thinking about what I want to do with my testing, I want every option on the table. I don't want a document to "guide" my thinking by limiting my options to the sections it contains.
Later, after I've done all the heavy lifting, I'll go back and format my document into the company template for that document. That allows me to add/remove sections as needed. The template does serve as a useful tool at that point. It serves as a quick check-sum to let me know if I've missed any critical piece of the equation or if I haven't thought something out enough.
This tip was part of a brainstorm developed at the September 2011 Indianapolis Workshop on Software Testing on the topic of "Documenting for Testing." The attendees of that workshop (and participants in the brainstorm) included: Charlie Audritsh, Scott Barber, Rick Grey, Michael Kelly, Natalie Mego, Charles Penn, Margie Weaver, and Tina Zaza.
Capture core information for defect in an automated fashion – if possible
When we submit defects, we often include a core set of data that's included on every ticket. For most organizations, this will include the submitter, the environment where the issues was discovered, the steps to reproduce, and often some sort of attachment showing or demonstrating the issue. In many cases, this core information can be captured and filled out automatically. Some defect tracking tools provide features that provide this functionality, but even if they don't a lot of times you can write a really simple script to populate a lot of this information for you. At a minimum, if your team has an expectation for some of these aspects to be filled out for all tickets, consider making those fields required to help ensure that each one is at least touched/reviewed before the tester clicks submit.
This tip was part of a brainstorm developed at the September 2011 Indianapolis Workshop on Software Testing on the topic of "Documenting for Testing." The attendees of that workshop (and participants in the brainstorm) included: Charlie Audritsh, Scott Barber, Rick Grey, Michael Kelly, Natalie Mego, Charles Penn, Margie Weaver, and Tina Zaza.
Submit an automated test that fails along with your bug report
We touched on this one before with this tip from Dave Christiansen, however the topic came up again at last month's IWST. Depending on the tools you use, you might consider attaching automated scripts to your defects. If you can find a bug, and then quickly record a simple script that recreates it, attach that and send it along with the defect report.
This tip was part of a brainstorm developed at the September 2011 Indianapolis Workshop on Software Testing on the topic of "Documenting for Testing." The attendees of that workshop (and participants in the brainstorm) included: Charlie Audritsh, Scott Barber, Rick Grey, Michael Kelly, Natalie Mego, Charles Penn, Margie Weaver, and Tina Zaza.
Leverage audio and video recording tools for bug reporting
In the past, we've shared a couple of tools for capturing desktop audio and video. In this post, we wanted to reinforce the idea of using audio and video recording tools for bug reporting. Instead of just submitting the steps to reproduce and a couple screenshots, try including a verbal description and show the bug or issue in action if that's possible. This often removes any ambiguity, and it can sometimes provide details to the development team that you may not have thought to mention (like the browser being used, or the screen resolution, etc).
This tip was part of a brainstorm developed at the September 2011 Indianapolis Workshop on Software Testing on the topic of "Documenting for Testing." The attendees of that workshop (and participants in the brainstorm) included: Charlie Audritsh, Scott Barber, Rick Grey, Michael Kelly, Natalie Mego, Charles Penn, Margie Weaver, and Tina Zaza.
Take photos of whiteboards and use those
It can take a lot of time to translate a whiteboard drawing into a Visio diagram. Sometimes it's worth the effort to do so:
- you plan on making updates over time
- you know that others will take the diagram and extend it in some way once you digitize it
- it needs to be a polished presentation for some particular reason
But many times, these diagrams are for one-time use. We create them to communicate a particular detail of the project, and then for all intents they just sit there - stale. In these cases, resist the urge to create them in digital format. Just snap a picture of the whiteboard with your phone, email it to yourself, and use that photo in any follow up emails or documents. This can save tons of time, and create a culture of more agile documentation.
This tip was part of a brainstorm developed at the September 2011 Indianapolis Workshop on Software Testing on the topic of "Documenting for Testing." The attendees of that workshop (and participants in the brainstorm) included: Charlie Audritsh, Scott Barber, Rick Grey, Michael Kelly, Natalie Mego, Charles Penn, Margie Weaver, and Tina Zaza.
Start with a picture instead of words
Often when I go to document something complex, I try to draw it out on a whiteboard first. I then go over to someone else's whiteboard and draw it out again - recreating it from scratch and explaining it along the way. As I do this, I get their feedback. Then I go find someone else, and do it all over again.
I keep doing this for a couple of reasons. First, it helps me clarify my thinking on the topic before I start writing stuff down. Second, I'm shortcutting the feedback cycle by getting direct feedback on the concepts before I codify them with a bunch of words on paper. Both of these lead to documentation that has both fewer words (because I'm more succinct and often include my pictures) and fewer rounds of edits (because people have already given me their substantive feedback).
This tip was part of a brainstorm developed at the September 2011 Indianapolis Workshop on Software Testing on the topic of "Documenting for Testing." The attendees of that workshop (and participants in the brainstorm) included: Charlie Audritsh, Scott Barber, Rick Grey, Michael Kelly, Natalie Mego, Charles Penn, Margie Weaver, and Tina Zaza.
Make sure everyone understands what’s actually needed
When you're trying to streamline your test documentation efforts, one aspect you should consider tackling early on is to get everyone involved into a room and to workflow what's actually needed by the various teams involved to be successful. This might include:
- What documents do we need to create?
- What sections do those documents really need?
- How detailed do those sections really need to be?
- What information do I need, to be able to write that section, and where do I get that information?
- What information do others need from me to be successful in their documentation efforts?
Once you've worked through that process once, make sure you check back periodically (each iteration, quarterly, annually, etc) to make sure there's still value in what's being created and that everyone is still clear about what's needed from them.
This tip was part of a brainstorm developed at the September 2011 Indianapolis Workshop on Software Testing on the topic of "Documenting for Testing." The attendees of that workshop (and participants in the brainstorm) included: Charlie Audritsh, Scott Barber, Rick Grey, Michael Kelly, Natalie Mego, Charles Penn, Margie Weaver, and Tina Zaza.
