RE: Developments in the review cycle

Subject: RE: Developments in the review cycle
From: <mbaker -at- analecta -dot- com>
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 7 Apr 2016 01:39:19 -0400

" 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.

Steve



---
This email has been checked for viruses by Avast antivirus software.
https://www.avast.com/antivirus


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

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


Follow-Ups:

References:
Developments in the review cycle: From: Erika Yanovich
RE: Developments in the review cycle: From: mbaker
RE: Developments in the review cycle: From: Steve Hudson

Previous by Author: RE: Developments in the review cycle
Next by Author: RE: Developments in the review cycle
Previous by Thread: RE: Developments in the review cycle
Next by Thread: Re: Developments in the review cycle


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads