Hi,
Have you explored any automated ways of generating documentation based
off the code?
Like a javadoc type system?
Maybe having an API reference as well as quick reference guides would
be helpful.
I find that having different "levels" of documentation helps
adaptation of the software to beginners and advanced users alike.
Thoughts?
I'm not a big fan of these systems for a number of reasons.
The primary one is that the quality of the information that you get
out usually suffers and, perhaps more importantly, concentrates too
much on the contents and structure and not on the *usage* of those
components. Systems like javadoc are wonderful at providing the
equivalent of a dictionary of the functions, their structure,
arguments etc. But you cannot learn how to use a language from the
dictionary. For documentation to be useful it needs to be more than
just the dictionary.
A secondary one (and one often related to the above) is that as a
general rule we developers don't always make wonderful documenters :)
That said, I think there are things that I would like to do within
Drizzle that we currently do not do within MySQL but which would make
the documenters lives significantly easier.
I developed the dynamic docs for the MySQL documentation that enables
us to document and track changes in specific elements of the system,
like the options and variables, and operators & functions and not only
provide multiple outputs (for example, the summary tables and the
individual item tables), but also to track differences between
versions. Currently the source for this information is a combination
of some automated systems that extract info from the source or a
running version of mysqld and our own manual (i.e. man-made) changes
to the source files.
With Drizzle, it would be a perfect opportunity to add in components
to the source that provide this information directly without us having
to manually (And sometimes badly) extract that information to provide
the base of the documentation.
That would cover a lot of the core utility of Javadoc like systems and
enable us to bond it together with the more useful user-driven
documentation of real usage, examples and so on.
MC
--
Martin MC Brown, Technical Writer
Database Technology Group, Sun Microsystems
http://sun.com | http://mysql.com
Phone: x18435/+44 247 669 8435 Skype: mcmcslp
_______________________________________________
Mailing list: https://launchpad.net/~drizzle-discuss
Post to : [email protected]
Unsubscribe : https://launchpad.net/~drizzle-discuss
More help : https://help.launchpad.net/ListHelp
