Sending to the list, because I missed the Reply-To-All button ;) ----- "Igor Galić" <i.ga...@brainsware.org> wrote:
> ----- "Leif Hedstrom" <zw...@apache.org> wrote: > > > 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). > > +1 > > > > > > 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? > > I guess that would be more than reasonable, and it would probably > help us in a sane transition. > > > > > 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 :) > > I just checked again, and those were lies. In fact, it was only > files which I converted. > > > > 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.). > > There are two parts to the CMS, one is the back-end. We don't have > to worry about bugs or fixes in the back-end. > > The other part is the frontend. That's our cup of tea. > (Or pint of beer to some). Here we decide how we would like the > to prepare or interpret certain things. This is where we > can put things like multi-language link generation or doxygen > reference resolution (that sounds really cool). > That's the part that goes into > https://svn.apache.org/repos/asf/trafficserver/site/branches/ats-cms/lib/ > > Regarding PDF support: This is just the way you *build* the docs. > There's pandoc out there, which can conveniently convert Markdown > to PDF > > > 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. > > Generally speaking: every .mdtext file will be converted to .html > The easiest way to split things up into multiple manageable chapters, > is to put the files which logically belong together into one > sub-folder. > > Finally, here's one of the best arguments for using something > like Markdown from a fierce competitor of ours (: > http://www.varnish-cache.org/docs/trunk/phk/sphinx.html > (reStructuredText is pretty much the same as Markdown) > > > > > Cheers! > > Thanks for the feedback Leif. > I'd really like to hear some voices of the folks who actually > write docs, before starting to implement anything that will > not find any love. > > > -- leif > > So long, > i > > -- > Igor Galić > > Tel: +43 (0) 664 886 22 883 > Mail: i.ga...@brainsware.org > URL: http://brainsware.org/ -- Igor Galić Tel: +43 (0) 664 886 22 883 Mail: i.ga...@brainsware.org URL: http://brainsware.org/
