----- Miles Libbey <mlib...@apache.org> wrote: > > On Oct 23, 2010, at 10:22 AM, Leif Hedstrom wrote: > > > On 10/23/2010 09:09 AM, Miles Libbey wrote: > >> What problems are we trying to solve by this effort? Do you envision this > >> replacing the cwiki, the documentation (Administrator and SDK Guides), the > >> site (http://trafficserver.apache.org/), or some combination? > > > > My personal view of "importance" here would be > > > > 1) Documentation (particularly SDK, but also Admin Guide). It's unwieldy > > to manage I think. I think a requirement in a "rewrite" of this is that > > it can produce documentations in some easily printable or distributable > > format (e.g. as a PDF file). > > ie, Docbook? (Shutters) It is the 'industry standard', but, it would imply > that we'll have some transformation scripts to produce both the HTML and > PDFs. Docbook is just XML, so, its more strict than HTML, but there are not > many free docbook tools and IMHO don't hide the complexity very well. > Regardless, I'm not opposed to tossing the current documentation setup, but, > I think we need to be quite clear on the problems we are trying to solve, and > make sure the new stuff will really solve them. >
Miles, I' not a particularily big friend of XML either. I'm not trying to throw everything we have right now. I'm trying to make it more accessible. > One problem we'll eventually need to solve is how to do translations. No > matter what code the documentation is written in, I don't think that's going > to be easily done. markdown can be easily converted in multitude of formats, PDF being one of them. The definite advantage, IMO over both XML and HTML is that you can concentrate on the content and that even people with no love for or knolege of these formats can easily contribute fixes. I haven't had the time today to bug joes, but for translations I'm imagining a format similar to the httpd docs. This can be taken over regardless of the format: index.html.en index.html.ch index.html.jp this can then be served via Options +MultiViews What we need to work out is how users will switch between languages for themselves. > miles > > > 2) Web site. This pretty much works as is IMO, and unless we get to the > > point where we add more content, I see little value in changing the web > > site right now. However, I think we need to get better at promoting some > > of the "drafts" out of the CWiki, and turn it into real pages on the Web > > site. This way, we can use the CWiki as the day to day work space, and > > the web site for all the 'released' official statements and documents > > (e.g. release plans etc.). This would also make a nicer user experience, > > making the Web site the "one stop shop" for all relevant Apache TS > > information. > > > > 3) CWiki. You'll have to make a really (*really*) hard sell to get rid > > of the CWiki. I'm not a huge Confluence fan, but I'm even less of fan > > of 'static content' web site / Wikis. It just simply makes no sense to > > me personally, and there are so many advanced CMS'es that could be used > > and would be "fast enough" (particularly if you put a web cache in front > > of them). > > > > Just my $.01, > > > > -- Leif > > > -- Igor Galić Tel: +43 (0) 664 886 22 883 Mail: i.ga...@brainsware.org URL: http://brainsware.org/
