Re: Developments in the review cycle

Subject: Re: Developments in the review cycle
From: Keith Hood <bus -dot- write -at- gmail -dot- com>
To: mbaker -at- analecta -dot- com
Date: Mon, 11 Apr 2016 20:03:36 -0500

It depends on how you define "finished". To ship with the product, the
documentation has to be clear, concise, well organized, easy to use, and
complete *as far as adequately covering the most important and most likely
uses of the product*. If your definition of "finished" documentation is to
have it polished to perfection and to cover every single thing that can be
covered about the product, you're doing yourself a disservice by taking on
too great a work load.

I found this interesting: "... finished (as in no more development is
possible)..." No more is possible? I have to think, never happen in this
reality. By the time you can get documentation to such an ideal state the
product will outdated and there will be a new version coming out, and
you'll have to dump working on document version X to start on version Y.
After that, taking version X to a point where there is literally nothing
more that could be done with it would be a pointless waste of time. If it
is possible to polish the documentation to such perfection, your company is
not moving. Law of nature in R&D: by the time they work out the last bug,
it's obsolete.


On Thu, Apr 7, 2016 at 12:39 AM, <mbaker -at- analecta -dot- com> wrote:

> " 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 bus -dot- write -at- gmail -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
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
RE: Developments in the review cycle: From: mbaker

Previous by Author: Re: Developments in the review cycle
Next by Author: Re: Temp agencies and job boards for local tech writers
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