Last week we discussed a couple of points on #ts-dev-weekly, R.I.P. I'd like to summarize the consensus we believe to have had on the Documentation agenda points, and put them up for discussion.
First off, I'd like to state that in our discussion we left out the CMS agenda point zwoop had sent out in his email. 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. 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 to function as the new reference documentation, and to use amc's Perl scripts to generate links from one to the other. (Once we branch off stable, we'd have to change this to the doxygen build of the branch, of course.) The ASF CMS =========== Some time ago, joes from infra initiated and pioneered a small project to make content distribution at Apache less of a paint point: http://www.apache.org/dev/cms.html A very good summary of this can be found at Paul's blog: http://journal.paul.querna.org/articles/2010/10/22/evolution-of-apaches-websites/ I've started an effort to migrate our current documentation to the CMS: https://svn.apache.org/repos/asf/trafficserver/site/branches/ats-cms/ 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 + I have laid out, or tried to lay out the whole thing for multilanguage. putting code to generate links for the other languages in: https://svn.apache.org/repos/asf/trafficserver/site/branches/ats-cms/lib/view.pm (search for LANG) In this same code we would put amc's Perl to generate the Doxygen references and something to generate a navigation. These at least are my naïve ideas. -- Igor Galić Tel: +43 (0) 664 886 22 883 Mail: i.ga...@brainsware.org URL: http://brainsware.org/
