So, here’s the question: What do software companies develop? Software, duh! But, for better or worse, this is not the only thing such companies need to worry about. Software is great and all, but it is useless if no one is sure how to use it. So, what else do software companies develop? Software documentation.
Who Creates Software Docs and Who Should
Workflows of creating documentation differ from one company to another. This task can be fulfilled by different departments: Developers, QA Engineers, Technical Writers, etc.
For various reasons, some companies simply don’t have a technical documentation team on their staff. In this case, a software company has several options: to look for an author among outsourcing companies or allocate some current resources to this task. Quite often, we see a company where Dev & QA are involved in tech writing. You can’t exactly call these folks Shakespeare’s descendants, these are mostly tech people, and not poets (with a few exceptions I’m sure 🙂 ), so, neither devs nor testers really enjoy this extra work. And, this is totally understandable – they certainly have some high priority tasks to do instead. In such situations, the user manual quality can suffer.
That is why, many companies prefer having tech writers on the staff. But, truth be told – not everyone gets the concept of a ‘technical writer’. To clear this once and for all – technical writers are people who create all kinds of technical documentation (user manuals, how-to articles, knowledge bases, context help, etc.). They get to learn about every new feature or change before the release happens as they need to describe every detail for end users. When some feature or a bottleneck is not documented, most likely, an army of angry users will sharpen their pitchforks, light torches and go have a friendly chat with… tech support. So, techwriters were brought to this world not only to improve user experience via writing help articles, but, also, to decrease the workload of support teams.
What About QA?
With this figured out, let’s take a closer look at documentation itself. A word I would pick to describe it for a software company – unavoidable. It won’t matter if you are using agile software development or the waterfall model – you can’t get away from writing user manuals each sprint (evil laughter.mp3).
It’s hard to separate software documentation from R&D. And, you really don’t have to – documentation is as essential for a software product as its code.
It seems we can’t escape the following conclusion: technical documentation should be treated right. For example, user manuals should be tested . And, the QA Team is the best choice for testing user manuals. Because, basically, techwriters and tester are the first real users of new features. So, they are the first to know when something is inconvenient, unclear, too complicated, etc.
When tech writers are documenting a feature or an app screen, it may seem okay for them in the context of the feature purpose. While the QA team will approach the same thing from a different angle. If you give this feature for review to testers, some peculiar feedback might return – QA will look at this from the practical side, they are focused on real user experience with product functionality. So, testers can address the documentation team afterwards and ask them to re-write the article or elaborate the description.
Sometimes, this happens the other way round – the QA team reads documentation, which describes how some feature should work, and understands that this is not working as expected, and this is a bug they knew nothing about.
As you can see now – such team collaboration can be highly productive and useful to improve both the documentation and the software quality.
QA and Technical Writers Collaboration: How To
How should this team collaboration be organized? What kind of a workflow will suffice?
The easiest way is using email. A document is created, it is sent via email. Later, you get some feedback and make the necessary changes in the initial document. This scheme is used by many companies. Just because it’s popular doesn’t mean it’s good. Just stop for a sec and think of all the flaws of this approach: emails get dragged into spam folders, fail to be delivered at all, get lost among hundreds of other messages. This process is long and painful. Let’s look for a more formalized document review approach that does not have those problems.
It is clear that the decision depends on the tool the tech writers use for documentation authoring. For example, MS Word is a poor choice of software to create software documentation in. There’s a wide range of specialized software documentation tools , designed to make collaboration and documentation review easier. As a rule, such tools feature a special workflow for documents – an assignee, a status, etc. This is very helpful in terms of understanding who’s working on a document at the moment and what’s the work progress (draft, under review, ready). Besides, suchlike systems often allow adding comments so the reviewer can leave some notes on the content for the author to consider them later.
Web-based documentation tools (for example, ClickHelp ) are the best choice for this task as they do not require installation of the client application to collaborate with the documentation team. The only thing you need is a browser. This simplifies creating of a correct and efficient scheme of documentation review between technical writers and testers.
Conclusion
Collaboration is very often the key to success. Try to implement the approach described in this blog post – involve your QA team in working on documentation, and make sure your technical
writers use a good documentation tool. This will increase the user guide quality, increase user satisfaction with your software, and can even increase the number of successful trial users who convert to customers.
*About the Author – ClickHelp Team*
This guest blog was written by the vendor of the ClickHelp online documentation tool. ClickHelp is a modern browser-based tool in the cloud. It can produce online and printed documentation, knowledge bases, PDF docs, context help, policies and procedures. ClickHelp combines a documentation authoring environment for teams, and a documentation portal for end-users.
To learn more about the ClickHelp documentation tool, visit this website: https://clickhelp.co
Leave A Comment