Is it common for testers to write the product documentation?

šŸ—„ļø Archive
1

Hello! In our organization, we have SDET and manual testers. Our manual QA testers are responsible for all acceptance testing which is primarily exploratory. Weā€™re starting to dabble in written test cases but havenā€™t decided whether thatā€™s the best route for our team.

We are however, responsible for writing the product documentation used by all the departments in the company (primarily our customer experience team). Is this a common QA responsibility? How is that responsibility handled at your company?

Bonus Q: Iā€™m curious if test cases in a test case management suite can be used as de facto product documentation as well.

6 Likes
2

Nooo, hereā€™s my rant from another discussion on this. I caveat my rant with there are times on occasion given a tester will often have the best knowledge of the product it may make sense but I strongly recommend against QA getting associated with being the documentation person.

One other flag that may be worth raising, it in my experience is not good for testers to get known as the documentation person.

There are still people out there that feel testing is all about documentation, writing test cases, reports, release notes, bug reports a lot of things that may be useful though tend to carry a lot of waste in my experience but still often detract away from actual testing.

Iā€™ve seen places where some managers were sub consciously seeing this to the extent that the QAā€™s were more often than others taking meeting minutes at retroā€™s for example. Itā€™s can be both a bit disrespectful and diminishing to helping people understand the real value of testing.

I for example will almost never volunteer to take meeting minutes due to that risk, taking your fair share of documentation is one thing but do not get a rep as a documentation person.

5 Likes
3

With @andrewkelly2555 on this one. Never let someone who knows the product very very well write the documentation for it. I like writing docs too, donā€™t get me wrong, but , emmm.

I am guessing this is an ā€œinternalā€ product @wrenarf , and my rule for this still holds after 30 years of coding. Developer writes the 1st draft of the user docs, just to force them to think about what they built carefully. Then someone who has used the product, takes over and re-writes that documentation on a regular basis, to reflect changes in language, process, ecosystem and workflow. I would try not fixate on who should write docs, so long as it is not someone with actual skin in the game. Personally I would thus push back on being he documentation writers here.

Tests as documentation. Not sure that is not bordering on incest. Although admittedly it is often tempting to come to this kind of conclusion, (yes I have had this thought many times, so ban me) doing so feels like a bodge (square peg into a round hole).

Oh, and Hey Wren. Welcome to the Ministry of Test Club! Great starter question right there, do return and tell us more so we can learn about the process too.

4 Likes
4

Weā€™re lucky and have two dedicated technical authors, that take care of external customer facing documentation.

For internal documentation we do often produce internal documentation for other teams - so for particualarly complex pieces of functionality we will take detailed documentation that has been produced by engineers and turn into something appropriate. I think, where we as test are well positioned sometimes, is to understand the stakeholders better than the engineers. We produce a lot of embedded software, which is used on precision instruments. The engineers typically solve complex problems - and their designs reflect that comlexity. We cannot, however, put their design documentation infront of - say - a customer service engineer. They just lack the skills to understand how a feature will work from that level of documentation, so we as testers - since we have to understand the needs of the stakeholders to test the thing in the first place - often end up distilling these down to application notes, or other short form documents with the appropriate level of detail.

These arenā€™t used as part of testing, so weā€™re not preducing the day job so to speak - weā€™re helping teams out with our understanding that has been gathered over the formal testing process.

As for the bonus question, I havenā€™t seen that done. Our test cases link back to requirements and then back to features in Azure DevOps, but these would be too low level for most stakeholders to get a grip on for my money.

2 Likes
5

I think that in an ideal world, there would be technical authors to write the product documentation. I see it as being like testing: as many people as possible should get involved, but there should also be dedicated experts who make sure the outcomes are as good as possible.

Testers definitely have lots to contribute, because of their knowledge of the product. But so too do customer support people, as they know how outside users experience the product. And developers I hope should contribute too.

I donā€™t think that test cases should be seen as adequate product documentation. Theyā€™re better than nothing, but theyā€™re designed to help with testing, not to help someone understand. I find it helpful to see documentation as a designed thing, like software is. For more, see my upcoming MoT workshop on technical writing :wink: Express Yourself More Effectively In Writing | MoT

2 Likes
6

Hi @wrenarf ,

A warm welcome to the community. :wave:t2: And congrats on taking a leap and asking such an excellent question.

At various companies Iā€™ve worked at Iā€™ve not experienced testers writing product documentation. The closest Iā€™ve seen is when I would update acceptance tests using Gherkin syntax (and developers would implement them as automated checks).

Each scenario of the acceptance tests would be signed off by the product team so they could then prove to regulators that tests (checks) were in place. Context: This was for clinical trial software.

I do like it when testers use contemporary exploratory testing techniques to capture long-form notes (written and video) as they timebox explore a test exploration goal. Thereā€™s something about the output of such notes that informs product documentation.

2 Likes
7

To be the devils advocate here, there is one trend which talks about the T-shaped people in your cross-functional teams. Which goes a little like, my expertise lies in Front-end development / back-end development, test, database design etc. But I dabble in anything that is needed. One reason for this is that it allows the team to focus on delivering value instead of concerning themselves with time allocation. I.e. oh we need a database task because the database person have nothing todo, even if this is not the most valuable thing we have to work on. So if the reason why the QA team is writing the product documentation is because that allows you to maximise produced value in the team then it sounds like you are on to something.

In my experience tho itā€™s more a lack of understanding of the value that the QA brings that results in the idea that QA can write that documentation. (I.e. they have nothing more important to do). In the places I have worked product documentation have often been written by Tech Writers and reviewed by testers, or not been produced at all. If that answers your question.

As to the bonus question. As a general rule I favour the single responsibility principle for most things, included documentation. That is, that if you decide that this is the Customer Experience Handbook for Happy Customers, instead of Product Documentation it is more likely that it will be well made than trying to target different audiences with the same thing. Because of this I am already very sceptical of test cases or test case management suites, because they tend to grow into ā€œone artefact to rule them allā€. A few examples being, help new testers learn about the product, help plan the test effort, help distribute the testing problem, report status to project management, report the results of the testing, guide a tester on what to test. Those are a lot of missions for a poor little test case. The problem with this is that instead of doing one thing really well, it does a lot of things poorly. First, if anything I would suggest that you flip it. Have a product documentation as input to testing, not testing as an input to product documentation. And in the world of Context Driven Testing or whatever the name for it is today it already exists and is called Claims Testing as a technique. Where you basically look at what claims the product makes about what it should and should not do and you use that as basis for the test design (not exclusively but as one of many inputs).

3 Likes
8

I also think that testers should not be the(only) ones who write documentation.

Documenting is ideally a team effort and not a single persons duty. In my opinion the person with the deepest insight of a topic should be the one who is also documenting it.
For instance:
Developer X implements a new feature. Part of the implementation is also updating the documentation.
Tester Y sets up the initial environment for E2E tests. Part of this is also to update the documentation.
Architect Z designs the architecture of the productā€¦

Speaking from experience you also need one person who ā€˜ownsā€™ the documentation. This is important to keep the documentation up to date and also consistent. This can be a tester, but does not have to be. This person should however have a good overview of the product.

Another point what also speaks against that testers write documentation is that documentation is also an asset which can and should be tested.

2 Likes
9

(post deleted by author)

10

This is definitely how we wound up doing it. Initially as a small startup team, we didnā€™t have product documentation at all. We started to grow enough to where we needed it and at the time, qa felt the need for it the most so we just started doing it. I think we went wrong when we started hiring additional people and building additional teams and didnā€™t diversify that responsibility at that point. It just had been something that qa had always done so we moved it forward that way. I love the concept of testers reviewing the docs (and contributing) rather than always writing them.

Thatā€™s great insight on the test cases. Up until about a year ago (I think Iā€™ve been in this role 7 years now) we did not have written test cases so itā€™s a total new frontier. We absolutely need to hone in on what they actually mean for the department.

1 Like
11

This has been a heck of a lot of really great insight - thank you all! I have a couple more questions to dig in a little further:

In cases youā€™ve mentioned where the documentation responsibility is shared across the team - is that all on the product/development end of things or do you see customer experience people involved as well?

In your experience, where in the lifecycle of a story is it best started? I know in our case it definitely continues being revisited upto and after release to production, but Iā€™m debating on when makes sense to begin. Once the story is groomed the first time? Once implementation has begun?

2 Likes
12

I do not think it is common practice however of the last 5 places I have worked, product team has maintained the documentation in 4 of those places.
Currently where I am - for some reason the QA team does document the product requirements on Confluence!
I donā€™t agree with it, itā€™s mainly because the old product team
a) do not understand the requirements / how the features work
b) donā€™t have time / canā€™t be bothered.
c) if our QA donā€™t write up the requirements there is a massive gap in essentials documentation for new and existing features.
I am glad to report that this is now changing after 1 year+. I guess the thinking is that the testers have the most hands on knowledge of how the feature works end to end so why not let them write up the wiki pages!

2 Likes
13

Hey @wrenarf and welcome to MoT!

I donā€™t think itā€™s common, at least not where Iā€™ve worked. Functional analyst pick this up with a developer to work together on the technical writings. Our testers do review the docs!

1 Like
14

In my opinion, Documentation is the process that helps simplify future tasks as any tester, developer, or business analyst working on a project could consider reflecting on the past precedents.

As long as it comes to preparing documentation by QA teams, we follow and encourage our clients to start documentation at the earliest stage of the product development lifecycle. This means the process involves developers, testers, business executives, analysts, and anyone who is directly or indirectly associated with the project.

Such an approach helps to bring more depth to the overall process making the process of documenting easier and of course, more detail-oriented.

2 Likes
15

Welcome @wrenarf to MoT. :smiley:

In my current context we have a Technical Content Author who primarily writes the product documentation. In terms of where QAā€™s have fit into that stream of work Iā€™d say weā€™d either be verifying what the feature is doing or sometimes asked for a review of what has been written. This is sometimes done out of just access to other persons at the point of it being raised but Iā€™ve only been asked to review it during the editing process. The issue of responsibility is a broad one as others have mentioned but I donā€™t think itā€™s your sole responsibility. This is of course if your product team has the budget for a Technical Author/Writer to be a part of the development of the product and in the case of where there isnā€™t it unfortunately and unintentionally falls to the SME.

2 Likes
16

Not sure if itā€™s common but Iā€™ve helped out on a few projects in the past

Sometimes the documentation has been seriously lacking (eg. Just a title and no description) and since I had the time and energy, I would hold meetings with the team and make them more understandable for our team

1 Like
17

Welcome to the MOT @rudraneildutta . Wow I can see so many of the jobs Iā€™ve been in in that input. People often think testers have free time, or (although we know the product well) that we are best placed to describe the user workflows and requirements. Good to see you have been able to shake things up as well.

Do keep sharing, this has been a revealing discussion to all.

2 Likes
18

In software testing company working on volume testing, load testing and performance based testing, do not give even a little importance to the documentation as much as they give to the software development process. However, the fact is projects that have all the documents have a high level of maturity and careful documentation can save an organizationā€™s time, effort and money.

Test documentation is documentation of artifacts created before or during the testing of software. It helps the testing team to estimate testing effort needed, test coverage, resource tracking, execution progress, etc. It is a complete suite of documents that allows you to describe and document test planning, test design, test execution, test results that are drawn from the testing activity. For a newbie, itā€™s easy to assume that Testing is executing the various section of code on an ad-hoc basis and verifying the results. But in the real world, Testing is a very formal activity and is documented in detail. Test Documentation makes planning, review, and execution of testing easy as well as verifiable.

The degree of test formality depends on

  • The type of application under test
  • Standards followed by your organization
  • The maturity of the development process.

Testing activities generally consume 30% to 50% of software development project effort. Documentations help to identify Test process improvement that can be applied to future projects.

There is the necessary reference document, which is prepared by every test engineer before stating the test execution process. Generally, we write the test document whenever the developers are busy in writing the code. Once the test document is ready, the entire test execution process depends on the test document. The primary objective for writing a test document is to decrease or eliminate the doubts related to the testing activities.

If the testing or development team gets software that is not working correctly and developed by someone else, so to find the error, the team will first need a document. Now, if the documents are available then the team will quickly find out the cause of the error by examining documentation. But, if the documents are not available then the tester need to do black box and white box testing again, which will waste the time and money of the organization. More than that, Lack of documentation becomes a problem for acceptance.