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 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.ā€

8 Likes

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.

4 Likes

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!
Beren

2 Likes

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.ā€

3 Likes

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.

https://developersbestfriend.com/2016/11/04/saying-goodbye-but-how-will-you-remember-me/

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.

4 Likes

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

I saw a discussion pop up on Slack this week which I thought related to the replies here pretty well & was worth sharing

Iā€™m curious how you all keep all your testing and general project information organized. Iā€™m talking about all the information youā€™d need to be able to hand off your project to another QA should you get sick/win the lottery/leave, etc.
When I go on vacation, I spend some time writing up a document either including or linking to other documents that include information such as:

  • Who is on the project?
  • What is the project about (1 or 2 lines)
  • Test URL
  • Test user credentials
  • Other test data such as test credit card numbers or images to upload
  • Quirks of the project

I want to create a template that I can quickly fill in and easily keep up to date so that it is available for reference by me and the team and also ready to hand off if the need arises.

The automated tests (of every level) can serve as great documentation. Them, combined with reduced complexity overall will be extremely helpful.

However, I will add that, since most of us here are likely on teams that claim to be ā€œAgileā€, there should be no need to hand off to another QA person should you not be available, as the rest of the team should have absolutely no problem picking up that slack. QA folks tend to excel at finding bugs that exist in emergent behavior of the SUT. These are the edge cases that no one considered. The developers should have a sufficient grasp of the defined behavior of the application to handle any testing needs while you are away, and they should already be contributing in this way regularly. Without this, the team isnā€™t ā€œAgileā€.

Hmm some stuff I do,

  • scripted test cases in AzureDevops Test Manager
  • automation incl comments + email will be sent after each run about success/failure
  • confluence for more description, details, information
  • shared GoogleDrive/Folder for test files, storing old test data and results
  • regular knowledge transfer to present latest changes, e.g. the new test suite incl. test cases and documents which will be recorded.

I do this continuously, so when leaving for vacation I just give a short summary of open stuff, but this usually not more than 5 to 8 lines in an email