Re: How do I document vaporware?

Subject: Re: How do I document vaporware?
From: Stuart Burnfield <slb -at- westnet -dot- com -dot- au>
To: Techwr-l <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 28 Jan 2009 13:23:21 +0900 (WST)

Geoff Hart said:
> Skywriting? <g>

Geoff, you're an evil, evil man ;^)


Sarah Stegall wondered:
> Having spent half a week taking all references to a certain
> feature OUT of our software documentation, I am now informed
> that these references are "placeholders" for future development.
> This means that when our users (other software developers)
> browse through the command line interface or the help menu,
> they are going to find undocumented commands (that don't
> currently do anything anyway).

Wow, what a bad idea. But you already know that.

Geoff Hart said:
> Then add a clear note at the start of each feature description:

Yes, put an unmissable note at the start of every topic that
discusses one of these future features. But be really careful
with the wording.

> "This feature is not yet implemented. When it is implemented,
> it will perform the following functions
> [description].

This sounds like a commitment that it _will_ be implemented,
and a commitment that the syntax and behaviour will be as
you have documented.

What if a customer starts designing or coding based on the
documented interface?

Does your company have a legal department? Can you ask
them to come up with a wording that protects the company
if a customer sues them over 'promised' features that aren't
delivered or that work differently than advertised?

Stuart

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

ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals.
http://www.doctohelp.com

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.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-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

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

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


Follow-Ups:

Previous by Author: RE: Need some opinions on phrasing
Next by Author: Re: Need some opinions on phrasing
Previous by Thread: Re: How do I document vaporware?
Next by Thread: RE: How do I document vaporware?


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


Sponsored Ads