Re: Documenting internal programs

[Jim Purcell <jimpur -at- MICROSOFT -dot- COM>]

Tracy Jones asks:

> My company is launching its first software
> applications for external users-- I wrote online documentation for two
> of
> them, an instruction sheet for a third, and revised two other sets of
> documentation written by engineering interns (boy, that was fun!). The
> released versions don't contain some of the elements of our internal
> tool
> sets. I'd like to start documenting these internal, undocumented
> features
> because 1) I know someone will want to add them to the next released
> version
> 2) Only the engineers who wrote them know how to use them
>
> My question is: how do I get support for documenting these internal
> tools?
> What argument would persuade my boss that this will be time-saving and
> cost-effective in the long run?
>
If by "internal" you mean "internal software functions that are
invisible to the user," you don't need to and shouldn't want to document
them. Explaining internals only sows confusion, and even an accurate
knowledge of internals doesn't make users perform better. As far as the
documentation is concerned, to add to today's parade of pithy sayings,
if the user can't see it, it doesn't exist.

If by "internal" you mean "in-house tools" and you're thinking there may
be a market for these things, talk to your marketing people and
development leads.  Find out if there are any plans or interest for
turning these tools into products. If there is, you'll have to document
them eventually, but now may still not be the right time. By the time a
tool gets turned into a product, it will probably be changed beyond
recognition. A slick user interface will no doubt be required, and other
bells and whistles will surely appear before the things go out the door.
If you start writing too soon, you're in for a lot of rework.

If there are no plans to market in-house tools, whether it's
cost-effective to document them depends on several things. How difficult
are the tools to use? How do new hires learn the tools today? How long
does it take, and how much does it cost? How much would documentation
cost? How often are the tools modified, and how much trouble and expense
would document maintenance be?

Unless there are serious plans to turn the tools into a product soon,
your managers will probably (and rightly) treat this work as a low
priority. Documenting in-house tools is overhead. Your managers (and, I
hope, you) want you to be generating revenue, adding value, and all
those things that look so good on your performance review.

Jim Purcell
jimpur -at- microsoft -dot- com
My opinions, not Microsoft's

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html