Re: Documenting the way software actually works WAS: Try selling the sizzle of what you do.

Subject: Re: Documenting the way software actually works WAS: Try selling the sizzle of what you do.
From: Paul DuBois <paul -at- kitebird -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 17 Feb 2003 11:27:14 -0600


On Mon, Feb 17, 2003 at 09:09:43AM -0500, Sue Ahrenhold wrote:
> >>That is never a question. Documentation documents actual behavior,
> >>or else it is fiction.
>
> Way TOO simple an answer for me.
>
> The answer to this question here is: Well, is it in the bug tracking system? Will it be fixed before the release? If it isn't fixed, have we put it in the Known issues section of the Release Notes?
> If these are true, then document it the way it's supposed to work.

Hmm, I don't think you've contradicted me. Your final sentence assumes
that it's documented *somewhere* how the software actually works.

> At many smaller companies, the documentation is also the functional specification.

And it's of little value if it documents what's supposed to happen if it's
not *also* written down somewhere where the software deviates from
that specification -- that is, if it's not also written down somewhere
how it actually works.

I can't imagine the engineers being happy with a functional spec
that isn't accompanied by documentation in some form that tells
them where the spec fails.

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

Buy or upgrade to RoboHelp X3 today and receive the WebHelp
Merge Module for FREE ($299 value). RoboHelp X3's all-new
features include conditional text, completely re-engineered
printed documentation output, Context-sensitive Help Toolkit,
single-source layouts, and more!
Order online today at http://www.ehelp.com/techwr-l


---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.



References:
Documenting the way software actually works WAS: Try selling the sizzle of what you do.: From: Sue Ahrenhold

Previous by Author: Re: Try selling the sizzle of what you do.
Next by Author: Re: use other color for new text in Word
Previous by Thread: Documenting the way software actually works WAS: Try selling the sizzle of what you do.
Next by Thread: Re: Documenting the way software actually works WAS: Try selling the sizzle of what you do.


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

Sponsored Ads


Sponsored Ads