On 11/22/2010 10:36 AM, Igor Galić wrote:
I'd like to summarize the consensus we believe to have had on the
Documentation agenda points, and put them up for discussion.
Excellent, thanks for taking initiative on this! My comments are in-line
(but, I'm not a docs person, so take my "concerns" with a grain of salt
please).
Doxygen for Reference documentation
===================================
For quite some time, we've had a buildbot build of the doxygen docs:
http://ci.apache.org/projects/trafficserver/trunk/doxygen/
amc suggested to use this as a the reference documentation.
That has the advantage that we won't duplicating the efforts.
He also provided us with a friendly email and with some nice Perl to
generate links form the developer documentation to the doxygen part.
http://people.apache.org/~amc/WikiVar.html +
http://people.apache.org/~amc/tiphares/home.html
My proposal is to replace the current reference documentation
with the above doxygen documentation. The reason for this is quite
simple: TS-521 and TS-538 have rendered the documentation useless.
Two things comes to mind here
1) We need to move a lot of the existing "reference" documentation from
the current HTML docs into Doxygen format. The current doxygen format is
very incomplete, and not particularly up to date.
2) Where does all this documentation go ? If it goes into ts/ts.h (which
has some, but not complete) Doxygen docs already, doesn't that risk
making the public ts/ts.h file extremely large (MB's potentially). If
it goes somewhere, e.g. proxy/InkAPI.cc, then we should also make sure
to clean up the existing doxygen docs from ts/ts.h, so that there's one
single place to manage all the reference docs.
My personal preference would be to keep the Doxygen docs out of ts/ts.h
entirely, except for a simple link for each function that points to the
generated Doxygen page (URL).
I suggest to have
http://ci.apache.org/projects/trafficserver/trunk/doxygen/
uploaded to:
http://trafficserver.apache.org/docs/v2/sdk/FunctionReference.html
and http://trafficserver.apache.org/docs/v2/sdk/FunctionIndex.html
Until we go there, would it be possible to, as a transition, just link
from the old docs into the Doxygen build URLs? To avoid being too
disruptive / complex, until we got everything sorted out?
The Admin guide is pretty much done, and up-to-date (except for the
records.config reference, but I've got an awk script to generate a
template from RecordsConfig.cc :)
The SDK part I only have started at ApacheCon, and so far I've gotten
around to doing the basics (license header) and get rid of the traffic-
server internal licensing documentation (code that has been ripped out, mostly).
I think further down the line we should get rid of the deprecated functions.
Nobody cares what was deprecated before we released 3.0-stable, and
right now that's the release we're documenting.
Right now what's most obviously lacking is a CSS (and the images).
Also a way to integrate an automagickally generated navigation,
would be a big +
How do we deal with bug fixes or extensions to the new CMS? Is there an
active developer community, or is the expectation that we'll have to do
CMS code changes ourselves? I'm thinking primarily for things that we
will need, that might not exist today (e.g. i13n support, or exports to
PDF format etc.).
Also, my "priority" for docs is still the SDK updates, since we're
making so much changes there, and then the Admin guide.
Finally, how does the CMS break things up into smaller files? I think
it's preferable to have some sort of separation, by chapter or
something, to make the files slightly more manageable.
Cheers!
-- leif
