Documentation so you can move on

Inspired by a tweet I saw from @friendlytester and the upcoming talk from @deament at TestBash Belfast, I was wondering if any of you guys have experiences of documenting so you can move on or preparing for the “hit by a bus” scenario?

Perhaps Nicola or Richard would be able to give some pointers about where one might start in this situation?

1 Like

Some of my initial thoughts when I realised I had to (or that I really should) leave some documentation for people on the projects were:
“What can I create (and not need to update/worry about updating) to help the project?”
“What testing related resources can I share with the team?” --> This was for a team where I was the only tester and that after I left one of the developers would be doing the testing.
“What translates well into written documentation?” (Some things are better communicated in a conversation towards the end of your time on your project)

I found which documentation I left behind depended a lot on the the type of skills I thought the team would have after I left (i.e. was there a testing gap?)

That’s what I worry about. I think about the possibility that the person coming after me might have 0 previous testing experience. They could be a fresh grad, I might not get the time to train them and I don’t want to leave them in a mess. If I leave too much documentation am I restricting their thought process or terrifying them into thinking they can’t do it.

I’m wondering if a Wiki as I go is a good approach for documentation and for my automation some sort of readme to go with it.

Creating documentation to train people is an expensive way of teaching. And If people have 0 test experience, do yo think documentation will help them? Also documentation is a very expensive insurance policy in case somebody might get hit by a bus… In agile we create less documentation and focus more on conversation between people.

As the picture below shows: often the most effective communication is face-to-face (ideally with some “tool” to draw).

Learning is often most effective when people get the change to try stuff with some guidance/mentoring/coaching of others. That’s why we explore to learn.

This graph shows that we learn more and remember better if we actively work with the product and with others. Reading stuff is not very effective.

Let me give you an example: I wrote a book with 7 others a couple of years ago. We spent 3 evenings brainstorming about the content of the book. We created a mind map to document our thoughts. After that we knew what the book would be about and which stories we wanted to tell. It took us 8 months to write it down. Why? Because writing stuff takes time. We worry about lay-out and spelling, we want to write it in a way that anybody will understand.

You say you do not have (or get) the time to train them. But do you have the time to write documentation? I would argue that we need time to get people up to speed. We also cannot expect wonders from fresh grads. Documentation will not help them in many situations. Teaching them properly will.

I am not saying you shouldn’t document anything. I would advice to use the first rule of documentation from RST:
“That should be documented.” really means “That should be documented if and when and how it serves our purposes.”


I guess I probably should have been more explanatory in my follow on. If I leave the company I then wouldn’t have time to train the new person. It is unlikely that you will hire someone who can start within your own notice period which is risky as the sole tester.

I agree reading isn’t very effective (particularly if, like me, you have reading difficulties).

@huib.schoots has already made the point I would have made, and likely more eloquently. So I will just support from an example from my personal experience.

When I first started testing, I did not know better. My first task was to write down an extensive series of regression tests for our system, which I did. This certification-approved scheme turned out to be very long, very precise, and was intended to be used to educate new colleagues about our system. Everybody except management took a turn at the tests, and after a couple of people I learned something important. The tests I wrote, in the way I wrote them were completely ineffective at teaching about what the system did, but were very effective at telling me who could follow a list of instructions.

After what I still refer to as “the incident”, which has little to do with trainging and a lot to do with testing (we had a release which passed every test we could think of and was very poorly received by our clients), we got the chance to revise the initial training.

I changed the system documentation as follows:

  • I borrowed the flow diagram from the UI guys. (1 page)
  • I borrowed the flow diagram from the hardware guys (1 page)
  • I summarized the two diagrams with plain text (1 page)

Then, when someone new was sent to test to learn about our system, I did the following:

  • I walked them through the system
  • I had a conversation (led by them) about what was going on. It had to be led by the new person, since they had different priorities for their role than I had, and I couldn’t effectively predict what they needed to know from me.
  • In the event of a programmer or tester, I allowed them to test a current scenario for a day (Session based testing, I give them a scenario, they have a few hours to test, then we talk about the testing), while allowing them to ask any question at any time.

What I noticed was this:

  1. People read and understood the documentation better than anything which was previously presented.
  2. After our department was “reorganized” (end of project), my old team mates would ask me to do the same for their new team, so the perception of the effectivity of that training was quite high.
  3. After training, my new team mates would be much more open in asking me questions than the ones who used the lengthy book of documentation.

As for my hit-by-a-bus scenario, that was covered by having team mates who understood testing (which, given that I talked to all of my team mates about testing every day, was everyone). I expected the following tester to make the tests their own. Which I suppose brings me to a following (supporting?) point.

It is often better to have a team which understands what you do than to have a document which describes it.


Maybe you don’t have the time to train the new person, but I guess you would have time to train the team as @brian_seg suggests…

1 Like

Thanks Huib!
I had a discussion about a similar topic just an hour ago with a colleague and this post served pretty great as a summarization (with some paraphrasing).
Some ideas that were given are now made a lot more concrete.

Discussion (50%) + Reading (10%) = 60%, but I’ve a feeling we’ve not seen the end of this.
Learning is a process of multiple activities. We’ll get to that 100% eventually. :wink:

Cheers again!


I guess as a perfectionist I’ll never feel like it is enough but I should be asking myself is it “good enough”. Thank you both :slight_smile:

I had a great tip before. If you are ever asked about something or how to do something take some time to document it, because chances are if 1 person asks about it more people will and it will save you time in the long run, being able to point them at some documentation.

I am also guilty of thinking I will forget something, so I try to document it with annotated screenshots, so I can go back to it. This has been invaluable recently when work started again on a product we looked at 18 months and were just maintaining since then. So I could point the new team at my documentation to help create useful test data.

And rather to be scared of out of date documentation I heard this saying today which definitely applies to me: “The faintest stroke of ink in a record-book is more illuminating than the most vividly-recalled memory.”


So… I am suddenly going to be that “here is a blog I wrote” person :unamused:

I wrote this last year. It is related to managing leaving, but with a different slant to “what documentation to leave behind”. It should at best be considered “possibly complimentary” to this discussion. It might be interesting to some.

1 Like

My preferred way approaching “hit by a bus” problem is pair testing and rotating work.

If there is no person on the team that is the only one that knows about a given subject, if they go, nothing happens.
The way to achieve that is to rotate work, and do not be the only person that tests that particular application.
One week you test it, the next week somebody else tests it. You use documentation and wiki to help smooth that process.

Documentation gets out of date and takes the time to create and is never as good as hands-on experience.


A reply I got to this via Slack:

The thing about documentation is that it is always there, and you don’t have to hassle repeatedly to reread it or get people at the right time. Having some is definitely very useful.
If you are worried about transferring your automation I’d suggest the following:

  1. How easy is it to run in a dev environment? If people can run it locally, they can debug it, and they have some hope. If you can script it or make it simpler do that. Make sure you’ve documented all of your preconditions. Stick in the exact commands, screenshots or video. Anything to make it as easy as possible to get it going.
  2. Some light diagrams about how the system fits together - structure and key flows. Just enough to help understanding - I like C4 as a diagramming standard.
  3. Notes about any weird stuff or gotchas where things don’t work as you might expect. You could comment the code, but a brief summary on the wiki is probably helpful for where to look or watch out for.
  4. If you think the person is going to be super new, maybe include a few pointers to things that will help them - intros to the language, page objects or other design patterns you use, forums to get help etc
  5. I had a brief article discussing the design choices I made and why, and offered a few other options for going in different directions. That was probably superfluous but I wanted to encourage their idea that it’s okay to change and I’m not mad)

And if you can, run someone one or more people on the team through it before you go.

Basically whatever you right the person is going to be drowned in too much information. But they are likely smart and will figure things out - what can you do to help them in that process?

1 Like