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.
" Say what? New product ships, but doco doesn't need to be in a 'finished
state'? Sorry, completely disagree. May as well ship no doco"
Between finished (as in no more development is possible) and none, there is
a very wide gulf. A printed book needed to be finished because once it went
to press it could not be updated again, probably for the lifetime of the
product. Finished did not mean perfect. It meant, we can no longer add or
change anything.
For a product to ship, you need a sufficient amount of documentation to be
sufficiently good. This does not have to mean finished. Without the
restraint of shipping paper, you can continue to make the content better and
to add additional content, potentially through the life of the product.
" whenever a user somewhere selects help, a request is generated for some to
be written."
Actually, we do that. It is called tech support. The result is called a
knowledge base. The fact is, we don't know everything the reader is going to
ask, or everything they are going to try to do with the product. We can't
answer everything up front. We have to put the product in the field, wait
for the questions to come in, and then answer them. What we don't have to do
is to keep treating the documentation and the knowledge base as two separate
things. We should be continuously improving the documentation, not creating
a separate knowledge base.
" why bother writing specs? Just wait until a developer is stuck on a
feature, or an end-user doesn't like the feature as provided, and generate
the need for a spec on the spot."
We do this too. It is called Agile software development. It is also called
Lean. The basic principles are that you don't build anything until it is
needed and that working software is preferable to a written design. When
done in a disciplined way, this is an enormously productive and efficient
approach which is practiced by most of the titans of the tech industry.
Finished means stopped getting better. Continuous improvement means you are
never finished.
Mark
-----Original Message-----
From: Steve Hudson [mailto:sh1448291904 -at- gmail -dot- com]
Sent: Wednesday, April 6, 2016 12:33 PM
To: mbaker -at- analecta -dot- com; 'Erika Yanovich'; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: Developments in the review cycle
> 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.
Say what? New product ships, but doco doesn't need to be in a 'finished
state'? Sorry, completely disagree. May as well ship no doco, and whenever a
user somewhere selects help, a request is generated for some to be written.
Taking this a step further, why bother writing specs? Just wait until a
developer is stuck on a feature, or an end-user doesn't like the feature as
provided, and generate the need for a spec on the spot.
Yeah, no need for a finished state, so no need for an initial state either.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
