Writing for Programmers, Summary

["Shelley Hoose" <shelley -at- a-frame -dot- com>]

HI all,

Thanks to you various techwhr-lrs for your responses to my request for a
discussion of writing for programmers.

I've discovered a lot this past week and most of it comes down to the fact
that there is little guidance for writing for programmers, probably because
the specialty is so broad.

The biggest challenge at this time for me appears to be organizing the
documentation while integrating structure architecture and diagrams,
database diagrams (entity relationships) and business rules/process flow.
How to document all this for the audience in a useful and useable fashion?
To do this, of course I need to know a whole lot more about the programmers'
needs and therefore their orientation, which means learning Java and SQL to
the degree that I can recognize what the goals are and find the business
rules.

After sitting down with the chief developer and picking his brain for
several hours last weekend, I have a much better idea of what the developers
need from this documentation and how I can go about getting what I need to
create it for them.

In addition, I got some great feedback from many of you Techwhlrs out there.
Here are some answers to the specific questions I put out:

1. Are there any particular references or resources out there?
Articles by Susan Gallagher (a fellow Techwhlr -- thanks Susan):
http://pw1.netcom.com/~gscale/susanwg/cmindware/article1.htm. See November
'99.
Construx.Com, a software engineering site, has a nice outline of software
documentation (although my supervisor inexplicably told me he doesn't like
it; don't know why, yet) :
http://www.construx.com/: Click on Sample Software Documents

The only book I found on guidelines for documenting any aspect of the
software development process: Documenting the Software Development Process
by Steve Ayer. currently out of print but I found it doing a Net search. It
just arrived yesterday; looks quite good.

2. What are the key elements to a systems manual -- what might a typical
outline look like?

One techwhrlr sent me his outline, which he knew might be of use but is
specific to his document:
-Preface (purpose, audience, organization)
-Introduction (Background, What is xxx, Features of xxx)
 -Technical Architecture Overview (diagrams and explanation of basic system,
definition of terms and concepts)
-User Interface Processing (In this program I'm documenting the GUI is
the frontend processing and the GUI files actually perform the
processing or direct the processing that the user asks for. It consists of
HTML code, ColdFusion code, and JavaScript (not Java).)
      -Database Processing (This the backend processing in the system I'm
documenting. Yours must have a database also if you are dealing with SQL.)
 -System Administation Functions (adding users, security)

3. Just what is a functional spec and what should it include?
"Read "the Mythical Man-Month" chapter on architecture vs. implementation.
(I haven't had a chance to do this, but will -- thanks!)

4. What about "entity relationship diagrams?" How might you construct
one?
One techwhrlr suggested getting the following book:Database Systems: A
Practical Approach to Design, Implementation, and Management, by Thomas
Connolly. It describes step-by-step how to do ER diagrams in great detail. I
got this book,and it does look great.

Another whrlr knew about a program which automatically diagrams the
relationships among your data tables: ERwin, or Platinum ERwin, is now made
by Computer Associates. Here is the URL:
http://www.platinum.com/products/appdev/erwin_ps.htm. While I've been told
that the database I'm diagraming is too complicated for Erwin, it might work
for others.

Also, I found that Visio Professional's database templates actually include
four different Entity Relationship Diagrams types (which are actually called
ERs in the business) to choose from. If you do a search on them, you find
that there are several different methods for creating an ERD and you can
ascribe to any one of these. I haven't had time yet to study them all, but I
will. After exhaustive Internet search, II found some really great links for
these: InCept, Inc at http://www.inconcept.com/publications/battle.html, an
article titled "Battle of the Modeling Techniques"; an article titled
"Documenting Your Database" from News In Review at
http://www.informationweek.com/656/56iudoc.htm; a bunch of stuff on Object
Relational Mapping Strategies (which I'll probably understand in a month or
so after more study) at
http://www.objectmatter.com/vbsf/docs/maptool/ormapping.html. Follow some of
the internal links at these last two and you'll find more related
information.

I got this definition as well (thanks): "The enitity relationship model
splits a database into "entities", e.g. employee records, and relationships,
e.g. "works-for/supervises". This simplifies both some searches and some
data design discussions. The relationships are always bi-directional, e.g.
if I work for you then you supervise me, and the relationship tables always
have only two fields.

Of course, you can accomplish much the same thing with a "supervisor"
field in every employee record.

ER diagrams are a design tool. Using them does not bind you to an ER
implementation."

General advice received (thanks Mike West):
"You should look to systems development textbooks and reference books for
things like functional specs, ER diagrams, flowcharting, etc.  Those are
system development tools, so you won't find much about them in Tech Comms
books, which focus more on the end-user materials. The standard system
development texts will cover the general topics. You might want to ask the
development manager, or a sympathetic developer, to recommend some books
thatreflect the preferred methodology. Perhaps they can lend you their old
textbooks. Perhaps there are some development documents lying around from
previous projects that you can use as templates.

Learning about Programming:
Another Techwhlr pointed me to a great tutorial on Java at
http://java.sun.com/docs/books/tutorial/index.html. It's well-written, with
good examples; overall a nice example of good documentation. And it's not
written for the already-initiated as are so many Java books ("...We're going
to introduce you to the wonderful world of OOP, but we assume you already
have some serious programming knowledge..." -- this is a typical disclaimer
at the beginning of most object-oriented books).

Good advice also:
"Study Java and SQL Server (or whatever you are documenting of course).
Start with the "Dummies" books on Java and SQL and go from there. And, as
Mike West suggests, seek out sympathetic developers. They can clue you in on
what's important to know about your product.

"Also, search the TechWr-L archives. There was a discussion about
documenting programming languages back in December of 1999. I saved a lot of
those
posts, because they had good advice. I know there have been other good
discussions in the past. (Look for posts from Michael Wing--I remember he
had some excellent advice on this topic.)

"Don't forget to look at your competitions' docs. Some of their writers
might
be quite knowledgeable, and you can learn from them what needs to be covered
in your documents. Of course, don't plagiarize, but do look closely at their
content and style."

More great advice:
"Learning what other writers did to make the similar material comprehensible
is only a small part of the making this particular type of documentation
work. This is not procedural documentation, and the level of abstraction
needed to connect the domains what can be done and why a developer should
dosomething a certain way is incredibly challenging.

"Build a rapport with sympathetic developers. They are probably your best
resource in any project. Reference materials and books on programming
techniques are fine, as far as they go, but I have found that most of the
products I document more often deal with the exception rather than the rule
where programming is concerned."

As others have said, you'll have to learn and the best place to start is
with books on programming, especially those related to your environment.

I'd also suggest looking at some classics. Anything by Jon Bentley, Date's
books on database stuff, "The Mythical Man-Month", Wirth's "algorithms +
data structures = programs" ...

And my personal favorite:
"In addition, you must develop two daily disciplines: (1) breath deeply
every
morning before digging into the work. (2) Smile; it unnerves people."