Re: [tlug] linux@example.com How many widely can we do that?

[Josh Glover <jmglov@example.com>]

2009/10/28 Curt Sampson <cjs@example.com>:

> I've never disagreed with that. But it's also hard (extremely hard, in
> fact) to write a specification without bugs when you have no way of
> testing it except thinking about it, and it's also very hard to keep an
> untested specification and code in sync.

I agree with that statement. I think the specification that is not
code should be of a different sort: a functional specification that
sets out what goals the system is trying to accomplish and goes over
the high-level design. API-level documentation can and should be
generated from the code (or *be* the code, as you suggest).

> If you've got a small, co-located team, you probably don't need
> nearly as much of that documentation as you might think. I do pretty
> large and complex projects with a whiteboard and a few text files as
> documentation.

The goal of the documentation is to communicate with teams that are in
a different location (and often, time zone). I agree that a small,
co-located team doesn't need to produce much documentation for its own
consumption, at least during active development. Maintenance is
another time when functional specs of the sort I mention above are
useful. How do you deal with maintenance work on complex systems your
team has written several years ago, or systems written by another
team?

> By the way, don't misinterpret this as me saying you must never have a
> specification outside of code. Sometimes, for various reasons, you're
> forced to code in a language entirely unsuitable for expressing a
> specification (though it does so anyway), in which case you may be
> forced to the inferior model of two specifications, one in a language
> suited for the specification, and another in some other implementation
> language that the compiler builds or the computer runs or whatever.

I don't think that a non-code specification should attempt to be so
specific as to answer *all* questions; as you point out, that is
precisely the purpose of the code. I think the non-code specification
should focus on things that are not captured in the code, such as the
motivations for design decisions, and especially the problems the code
is solving (probably stated in user stories, which are quite useful
for this sort of thing).

-- 
Cheers,
Josh