Re: Writing for programmers

["Sandy Harris" <sharris -at- dkl -dot- com>]

Shelley Hoose wrote:
> 
> HI all,
> 
> I've recently started a new job in which I am documenting software for
> programmers. It's Java with SQL Server at the back end. I don't really know
> anything about this stuff ...

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

As for the more specific questions, I can respond to some.

> 2. Just what is a functional spec and what should it include?

Read "the Mythical Man-Month" chapter on architecture vs. implementation.

> 4. What about "entity relationship diagrams?"

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.

> 6. What about the creation of structure diagrams and flowcharts? Are all
> those thousands of symbols in Visio really meaningful???

Yes. There's even a standard (from IEEE?) defining most of them.

> -- and if so, to whom?

Ask your developers and, if possible, your audience.