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