On Jan 13, 2010, at 2:55 PM, cmpil...@apache.org wrote: > Author: cmpilato > Date: Wed Jan 13 20:55:20 2010 > New Revision: 898937 > > URL: http://svn.apache.org/viewvc?rev=898937&view=rev > Log: > My first pass at categorizing the future homes of various Subversion > web documents. For the most part, this reflects some of my > fundamental opinions about website maintenance in our new Apache > world: > > * Keep the website focused on the general public -- the uninitiated > and general users. But bring developers into the source tree > ASAP. > > * Keep engineering documents with the code. Design documents, use > cases, translation HOWTO, HACKING, etc. all belong as close to the > code as possible, preferably in the notes/ directory (which itself > could stand some reorganization...)
In general, I agree with this idea. It's kinda painful to have to go search notes/, and then the website when looking for various docs. But.... Staring at plain text files can be painful (especially something as long as HACKING). Links within and between documents is useful, especially in technical documentation. Being able to link to a specific part of a document, such as the patch or log message section is invaluable. And it helps to be able to use non-ascii illustrations, variable-wdith fonts, font-size differences, etc. For all of these reasons, I'd like to advocate that we keep documentation in html, perhaps in a dedicated dev/ part of the website. And yes, this may mean that we move notes/ to site/dev/ . > I might change my mind on the items that are blog-like. If we get a > real official blog going, we could move all the letters to Linux and > Poole responses and stuff into the blog (along with real project > news). Or for lack of a real blog, perhaps we grow a > site/publish/news/ tree where that stuff goes.
