forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Gav...." <>
Subject RE: level of detail for docs (Was: svn commit: r437136)
Date Tue, 29 Aug 2006 09:07:04 GMT

> -----Original Message-----
> From: Ross Gardler []
> Sent: Tuesday, 29 August 2006 4:34 PM
> To:
> Subject: Re: level of detail for docs (Was: svn commit: r437136)
> 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.

Ok, that's good, that is what I meant should I alter it to in my reply just
before I got to read This.

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

Exactly that, if there are those that wander across my
Site, expecially the Apache web server installation tutorials, you would
Notice my style of writing on there at least is aimed at beginners and 
Very detailed and very pandering I suppose in my style. I've been doing
It so long I must remember that we don't have that same audience here and
To maybe stop being so detailed perhaps.

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, 

Meaning err on the side of not enough in case too much gets it wrong ?

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

Ok, the link is already there, I'll simplify and shorten the current
examples then, thanks for the comments.


> Ross
> --
> No virus found in this incoming message.
> Checked by AVG Free Edition.
> Version: 7.1.405 / Virus Database: 268.11.6/429 - Release Date: 8/28/2006

View raw message