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.
Actually, I would suggest that it is in the area of dangerous equipment that this approach is essential and has long been practiced. Of course, when we are dealing with potentially dangerous equipment the definition of âsufficient documentation for releaseâ is going to be different from, say, a smart phone app. But by the same token, the need to update documentation as new safety related information becomes available as a result of real world use of the equipment, is that much greater.
It is in this field that we have seen a documentation update mechanism in place for decades. In the paper era, this took the form of change pages, with manuals issued in binders, to allow for the insertion of changed pages, and often numbered by section, rather than consecutively, to allow for a logical page numbering scheme to be maintained when new pages were inserted. This was an information architecture explicitly set up in recognition that the manual was not finished when the product was issued.
Information about a product is created from the moment of its inception to the moment the last instance of it is retired. People need that information to get the best out of the product and to use it safely. The moment of product release is just one point in the history of information development about a product. That moment has certain specific information requirements associated with it, though these vary greatly from product to product and user to user.
The books-in-boxes model of documentation essentially says that there is only one information release for a product. There is nothing before the release, and there are no updates after. Documentation is finished at this point in the sense that there is a commercial decision to not add to it. But it is not finished in the sense that it includes all the high-value information about a product, since much of that information has yet to be discovered. (Also, some that is known may not be essential for release, and we donât have to hold up the release to get it published.)
In some cases, this model is outlawed by regulations that force the company to update documentation when critical new information becomes available. This is particularly true with equipment that is safety-critical or security-critical. But in many other cases, while it is legal, it is not commercially optimal, which is why we have technical support departments and maintain community forums.
But today we do not need to hand off ongoing information development to different groups or publish it separately from the documentation. We need a different definition of finished as it relates to our work and our role in the information development cycle of a product.
Mark
From: Kathleen MacDowell [mailto:kathleen -dot- eamd -at- gmail -dot- com]
Sent: Sunday, April 10, 2016 11:52 AM
To: mbaker -at- analecta -dot- com
Cc: Erika Yanovich; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Developments in the review cycle
Mark, your process is nice but I don't think it's a good fit for equipment, especially any type that could dangerous.
Kathleen
On Wed, Apr 6, 2016 at 10:30 AM, <mbaker -at- analecta -dot- com> wrote:
I have not only seen it, I have been actively encouraging it for many years.
But I think we first have to address the idea of "entire publication". In
the paper world, an "entire publication" was a collection of paper pages
bound together with glue. The publication process was massively physical
manufacturing process with complex logistics, and so the "content" part of
the process was really oriented around achieving a finished state at the
moment that the work went to press.
In online publication, whether that is a true hypertext or a books-on-glass
style PDF, there is no such physical manufacturing process and so no need
for a publication-wide definition or achievement of a finished state. We
still organize our processes around that concept, in many cases, but the
essential economic imperative for it has gone.
It a true topic-based information set (as opposed to a lego-block approach
to assembling larger documents) the topic is the unit of publication. It is
part of a much larger information set, but there is no reason for that
entire information set to ever reach a global finished state at a given
moment. New information is always turning up, and we are always discovering
new information about customers and their tasks that drive changes to
information and information design. An information set should be a living
thing.
In this environment, the topic is the only logical unit of publication and
the only one that can be meaningfully reviewed. However, that topic also
lives in an information set, and a reviewer may well need to see it embedded
in that information set to make sure it is fulfilling its proper role. (For
instance, do we need an example inline here, or is there a link to an
example?) Review should not take place in isolation, but individually in
context.
The model I encourage is to set up a work in progress server which publishes
the current state of the entire doc set internally on a daily basis. When a
topic is finished, you ask the reviewers to view it on the WIP server, so
that they see it in full context.
This requires much more than a change in review policy. It is a review
policy that is the logical outcome of a change in information design.
You have to review content in coherent units. A building-block topic is
usually not a coherent unit. An Every Page is Page One topic is a coherent
unit. Review policy follows information design.
Given that you make the changes in information design, however, review now
becomes much easier and more accurate. Review happens closer to the time
that the developer worked on the feature, and it happens in units and at
times that are less disruptive to their schedule. It is easier to see
problems in a smaller unit, particularly if it follows a well-defined
subject-specific topic type.
Mark
-----Original Message-----
From: techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+mbaker <mailto:techwr-l-bounces%2Bmbaker> =analecta -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf
Of Erika Yanovich
Sent: Wednesday, April 6, 2016 1:08 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Developments in the review cycle
In the "good old days", tech writers followed the Outline-First
draft-Second-draft-Camera ready model. We would submit an entire publication
for review (perhaps with some minor TBDs inside) and the world was a simpler
place.
What I see nowadays is more dynamic: partial drafts (or bunch of topics)
sent to different reviewers at different times. The stages are blurred and
the follow-up more complicated.
I know some of you don't believe in complete publications anymore, just in
separate topics that get compiled daily (or whenever) into a larger entity,
but publications are still alive and kicking out there.
So my questions are:
1. Do you also see this transformation?
2. If yes, how do you cope with it?
3. Should we manage each chunk separately according to the old model (sounds
a bit crazy) or replace the old model with a new one?
Erika
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and
content development | http://techwhirl.com
Looking for articles on Technical Communications? Head over to our online
magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public
email archives @ http://techwr-l.com/archives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
--
Kathleen MacDowell
kathleen -dot- eamd -at- gmail -dot- com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
