forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <>
Subject Re: level of detail for docs (Was: svn commit: r437136)
Date Tue, 29 Aug 2006 08:33:40 GMT
David Crossley wrote:
> Why do we need this level of detail? Surely the "SVN Book"
> explains it better than we can.

I would go for a half way between detail and easy lookup. What I mean 
is, it is useful to have a quick reminder on how to do something with a 
link to the full text in the SVN book. This way someone who doesn't know 
how to do it can look at the quick reference to find an easy link (which 
is easier than searching the SVN book). Those who can half remember how 
to do it but need a memory jogger with respect to syntax can just take a 
quick look on our page.

It's all very well saying (to paraphrase) "Forrest devs should know how 
to do it", but we have to learn somewhere. When this came up the first 
time I asked on this list because I couldn't find it in the SVN Book. 
Nobody here knew how to do it. Eventually a solution was found (because 
it was asked shorlty afterwards on the Cocoon dev list too).

I'm guessing Gav figured that, as a new developer who had to discover 
how to do this he would help tose coming later by documenting it in a 
simpler way. Pointers are a great help, the balance between too much 
detail and not enough is a hard one but I would err on the side of 
caution, just a syntax reference with a couple of basic examples and a 
link to the SVN book should do (i.e. lets not try and explain it, there 
are always exceptions).


View raw message