Hola, Maybe a better place for that high-level description of the file is the top of the file (which is automatically reflected in the top of the JavaDoc)... It helps with keeping to the DRY principle (http://www.artima.com/intv/dry.html).
Yoav On 3/16/06, Linda Tan <[EMAIL PROTECTED]> wrote: > > I agree. However, I think that a wiki page can serve the purpose of > providing a high-level description of the file. Trying to read a heavily > commented config file can be unwieldy if you're just trying to get a > primary understanding of it. > > -linda > > > -----Original Message----- > > From: Yonik Seeley [mailto:[EMAIL PROTECTED] > > Sent: Thursday, March 16, 2006 9:08 AM > > To: [email protected] > > Subject: SolrConfigXml page needed? > > > > http://wiki.apache.org/solr/SolrConfigXml > > > > This still contains references to solar, and doesn't contain > > everything that the example config does. > > > > My personal preference is to heavily comment the config files > > themselves (the first place people will look), and avoid repeating > > that in documentation. Too much documentation just gives people more > > to read, makes it less likely they will read it, and doesn't increase > > their knowledge at the end of it all. It also makes it harder to > > maintain it all and keep it correct. > > > > -Yonik > > > -- Yoav Shapira Nimalex LLC 1 Mifflin Place, Suite 310 Cambridge, MA, USA [EMAIL PROTECTED] / www.yoavshapira.com
