Hello,
When I want to get developers to write documentation for their code, I
can tell them to read the existing Doxygen manual, which is a pretty
good manual. But when they are finished and the library is ready for
other people to use, I'm facing a repeated situation of trying to get
another new bunch of people to actually _use_ the Doxygen-generated
documentation, instead of just reading the original source code :-(
I find that I'm spending a lot of time explaining that if they look
they'll find - well, all the lovely things that are the reason we use
Doxygen in the first (coloured and hyperlinked source browsing, the
various diagrams etc).
What we need is a how-to guide to introduce the users to the _idea_ of
Doxygen-generated docs, what sort of thing they can find (eg, the
coloured and linked source listings) and, more importantly, _how_ they
can find it. This would then be linked to in a prominent place on the
mainpage - and possibly at the bottom of every page.
This end-user manual could also be useful when introducing the program
to a new development team, before there is the opportunity to show them
their own code nicely presented (after all, they might not have had time
to write any code yet :-) ) - in a way that the "features" list in the
existing Doxygen manual can't.
Has anyone ever tried to write something like this? I'd offer to help
straightaway, but right now I'm a bit too close to the problem (it keeps
ending up as "For bleep's sake, just hit a few links and see for
yourself" :-( )
Regards,
Stephen Goudge
|
