Hello Pete -
I don’t have any suggestions for frameworks or technical tools
I will say, though, that there is no substitute for being committed
to and disciplined about creating documentation, and keeping it
up to date.
Don’t rely largely (or solely) on automated documentation tools.
Tools (for example javadoc) can help with some of the donkey
work, but they don’t write useful documentation without guidance
(informative “doc strings” and cross-references, etc.). An
automated index of classes and method signatures is worth
having, but, absent an explanation of both the “what” and the
“why” of the classes and methods, and an overview of the overall
architecture and its philosophy, such an automated index is
less useful as documentation than the code from which it
These automated tools also have the failing that they tell you
what there is, but not what there isn’t. Good documentation
will tell the user what reasonable expectations have been left
out and why – was it left out for good reason, or is it a feature
request begging to be made? – and suggest workarounds for
missing functionality, where possible.
Don’t let your documentation become too fragmented. It makes
it harder for the user to know where to look, and is more likely
to become inconsistent with itself (and the source code). I’m
tempted to say: javadoc, tutorials, wiki – pick two. (But that’s
probably excessively prescriptive.)
Be very, very skeptical of the notion that “We will write the code,
and the ‘community’ will write the documentation.”
In an open-source project, it should be easy for “others” to
contribute to the code base, but in a disciplined, organized way.
Documentation contributions should likewise follow a disciplined
protocol, and should have quality-control checks in place
equivalent to those used for the code.
I’ll also note that developers (in terms of knowledge, if not
temperament) are often the best positioned to write the
documentation for the functionality they implement.
Absent a structured documentation methodology, “community”
contributions to documentation are especially likely not to be
maintained across versions of the underlying code.
Just my thoughts …
I don’t have (and I don’t think there is) a magic bullet. Good
documentation is hard work. But software projects that invest
the additional resources to do the hard work required for good
documentation are more successful.