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. 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. 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 >
