TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Robert actually gives an answer to the question:=============
The Paligo review workflow management feature I'm using tracks which
reviews are open and which have been signed off on. It automatically
sends email alerts to reviewers if they're past deadline and to me
when they've signed off. If a bunch of reviews are open and we're
nearing release there's a convenient list I can pass on to the SMEs'
managers.=============
I think the issue is that documentation is becoming more like software. (And software more like documentation??? Save that for another discussion.) That makes the review process very different. In the software world, the main deliverable is bound to be online. A few things about that:* Nobody reads online doc as a complete work* Well, almost nobody* Interaction, search, connection to product are as important as content* Integration to community is part of content* Stuff happens fast
* Other???
So it's pretty clear that the old model of review has gone the way of the old ideas of "complete" or "done".Â
It seems reasonable that the only way to deal with this is to integrate doc review in with the software review. The business people (product managers) track the overall product -- whether the technology and features hang together as a "product" a human would buy and use. These people also need to track the overall docs from that POV. They will focus on delivery (interaction, integration, community) and at least categories of coverage.Â
For technical accuracy, SMEs and QA look at individual topics. These are associated with the specific features or product chunks. In Agile they tie to stories (I guess??? It's been a while since I've used actual Agile terminology). If these people are satisfied, and the product managers are satisfied, then the doc should work. For feature dev or changes, QA must be on board to also check the docs.
Community feedback is also important. This comes from customers (in a perfect world) and from field engineers. If they can't find what they need, it's time to bring solutions and proposals to the product manager and adjust.
This is essentially how we do it. We use ReviewBoard to get content in front of developers. QA also monitors that. We also do have commitment from QA -- they're pretty good about it. The feedback loop from the field has given us some good changes to the original assumptions.
I want tighter integration -- anybody with credentials should be able to log a JIRA issue from the docs, or post a comment directly to the pubs group from a given topic. We're working on that. Community also needs better integration.Â
Another direction -- move certain types of information into source control and treat it even more like software. I'm thinking of version info, tech requirements, support matrix, etc. A version cannot ship until these are reviewed and updated in source control -- outside of the docs. Then the docs can refer to that data where necessary. The more data that can drive development requirements and dependencies, the better. Never repeat it, just use it.
Does this solve the original question's problem? Probably not. But that problem is drifting into obsolescence. The user experience doesn't always include a single, wrapped up piece of documentation. Even if that's what you produce, it's not what the user sees. To effectively review the doc, you should look at it the way the user looks at it. My opinion...
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
