How do I document vaporware?

[Geoff Hart <ghart -at- videotron -dot- ca>]

Skywriting? <g>

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

If the software is even halfway competently designed, menu choices  
that aren't currently available should be greyed out, which is  
standard interface convention for both Windows and Mac -- and  
presumably Linux, though I don't use it and can only speculate. In the  
command line interface, the equivalent is a "this feature not yet  
implemented" error message if someone tries out a command that isn't  
yet enabled. However, people will want to know why something won't  
work and what to do about it:

<<There's no telling when these "features" are actually going to be  
implemented... What would be the best way to mention these in user  
documentation? I am afraid our users will be very confused when they  
happen across undocumented commands.>>

Get a jump on the next software release and document all of these  
things, but in general terms if the specs are nonexistent or unlikely  
to reflect the final product. Then add a clear note at the start of  
each feature description: "This feature is not yet implemented. When  
it is implemented, it will perform the following functions  
[description]. Until the feature has been implemented, you can  
accomplish the same goal by [description of how]." Replace the latter  
with "You can't accomplish that task with the current version of the  
software" if you can't get there from here.

--------------------------------------------------------
Geoff Hart (www.geoff-hart.com)
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
--------------------------------------------------------
***Now available***  _Effective onscreen editing_
(http://www.geoff-hart.com/books/eoe/onscreen-book.htm)

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

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