Re: Development documentation?

["Mike O." <obie1121 -at- yahoo -dot- com>]

Kirsten asked:
> Can anyone give me some advice, or a good book to read, 
> or a website to go to, so I can get started and learn 
> some basic internal-documentation concepts? 

Here are some of my thoughts on internal system documentation. I
never found any books or websites for this; this is just based
on my experience... YMMV. 

1. Software systems consist of components and interfaces. Start
by drawing a logical view of your system. Don't draw a physical
view until later. Draw boxes to represent all the major pieces -
those are your components. Then draw lines to represent
different types of communications between components - those
lines are your interfaces. 

After everyone agrees the drawing is basically correct, then
start writing an individual topic for each component and
interface describing what happens when it starts running. Focus
on inputs and outputs. Be very literal about what comes in and
what is returned. Make more detailed drawings zooming in as
necessary.

2. Work from the bottom up. Resist the impulse to start writing
outlines and overviews and conceptual topics. After you have
documented all the function calls, and documented the interfaces
betewen components, and have a good knowledge of the data model,
only then will you be qualified to start writing overviews. 

3. Don't get all freaked out because it's "developer
documentation" and is more technical than you might be used to.
Developers are users too, just of different systems. Take a deep
breath and start figuring out what they need, just like you do
when you start writing any user manual. 

4. If you are doing API docs, look at examples of similar API
docs first; there are plenty available online. Benchmark your
API docs against something similar. 

5. You really need a data dictionary. Use a tool like ERwin to
attach a text description to each data element in your data
model. If you ask for this, you might be told to do it yourself.
Try to get your developers to fill in at least an intial comment
for every data element. Then learn how to update the comments
and publish reports (sorry if I'm assuming you aren't doing this
already).

> just to capture information like "Yesterday, I fixed
> the widget that was all flooey in the Data Entry screen".

This example is really an issue of version control. Do they
check code in/out of a version control system? Most systems can
be set to force you to enter a comment when you check in code. 
The developer's manager has to hold them accountable for
recording this kind of information. Those comments should be
regularly scrutinized for accuracy and usefulness, and should
become part of the developer's performance review (good luck
with that!). 

Perhaps your company can review the check-in comments as part of
QA. Maybe you can start by distributing a summary of some of the
more interesting check-in comments, like "Made changes as
required," or the ever-popular "asdafasdaf."

Regards,
Mike O.



__________________________________________________
Do you Yahoo!?
Yahoo! Mail Plus - Powerful. Affordable. Sign up now.
http://mailplus.yahoo.com


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Order RoboHelp X3 in December and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at http://www.ehelp.com/techwr-l

Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!

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