'building forrest' documentation move?

[Dave Brondsema <da...@brondsema.net>]

The "Using Forrest" page describes the primary way of getting forrest to be via
CVS.  Unless anyone objects, I'm going to move the "Getting the Forrest source"
and "Building and Installing Forrest" sections into the "Contributing" page.  I
will replace those sections with a short description of installing the latest
release.  Also, the "Getting the Forrest source" section references the obsolete
"Forrest Primer" for specific CVS instructions.  I will take those out and move
them into the "Contributing" page.


-- 
Dave Brondsema 
dave@brondsema.net 
http://www.brondsema.net - personal 
http://www.splike.com - programming 
http://csx.calvin.edu - student org 

Re: 'building forrest' documentation move?

[Dave Brondsema <da...@brondsema.net>]

I have copied the CVS instructions from the old Primer and the building
instructions from the Using Forrest page into a new Building Forrest page.  I
put it under "Getting Involved", but it might be better under "Documentation".

The Using Forrest page now describes how to install a Forrest release, and it
links to the Building page for those who want to do that.  The relevant FAQs
have been updated too.

I haven't pushed it out to our website yet.

-- 
Dave Brondsema 
dave@brondsema.net 
http://www.brondsema.net - personal 
http://www.splike.com - programming 
http://csx.calvin.edu - student org 

Re: 'building forrest' documentation move?

[David Crossley <cr...@indexgeo.com.au>]

Marshall Roch wrote:
> Dave Brondsema wrote:
> > The "Using Forrest" page describes the primary way of
> > getting forrest to be via CVS.  
> 
> You must've read my mind... I was just about to complain
> about this. :)

Poor choice of word Marshall. If one "complains" in Opensource
then one tends to be ignored. Better to suggest, even better to
contribute a fix.

> > Unless anyone objects, I'm going to move the "Getting the Forrest source"
> > and "Building and Installing Forrest" sections into the "Contributing" page.  I
> > will replace those sections with a short description of installing the latest
> > release. 
> 
> What is wrong with the Building and Installing Forrest section?  Aside 
> from having a bunch of Ant lingo (targets) in there that you don't need 
> to understand to use it, it seems pretty good to me.

Yes, i think that this section belongs either where it is or in a HowTo
but not in the Contributing page.

> Also, "Getting Started" or "Quick Start" might be a better name than 
> "Using Forrest."  It details how to set everything up and create your 
> first site, and "Using Forrest" really could include all of the other 
> docs too.

I think that the intention of the "Using Forrest" document is to
provide a complete overview of Forrest. It should link to other
specific documents for more detail. Those other documents should
remind people to read the overview, as the content will generally
presume that knowledge as a base.

So far i am still happy with the name of the overview document.

--David

Re: 'building forrest' documentation move?

[Marshall Roch <ma...@exclupen.com>]

Dave Brondsema wrote:
> The "Using Forrest" page describes the primary way of getting forrest to be via
> CVS.  

You must've read my mind... I was just about to complain about this. :)

> Unless anyone objects, I'm going to move the "Getting the Forrest source"
> and "Building and Installing Forrest" sections into the "Contributing" page.  I
> will replace those sections with a short description of installing the latest
> release. 

What is wrong with the Building and Installing Forrest section?  Aside 
from having a bunch of Ant lingo (targets) in there that you don't need 
to understand to use it, it seems pretty good to me.

Also, "Getting Started" or "Quick Start" might be a better name than 
"Using Forrest."  It details how to set everything up and create your 
first site, and "Using Forrest" really could include all of the other 
docs too.

--
Marshall Roch

Re: 'building forrest' documentation move?

[Juan Jose Pablos <ch...@che-che.com>]

Dave Brondsema wrote:
> The "Using Forrest" page describes the primary way of getting forrest to be via
> CVS.  Unless anyone objects, I'm going to move the "Getting the Forrest source"
> and "Building and Installing Forrest" sections into the "Contributing" page.  I
> will replace those sections with a short description of installing the latest
> release.  Also, the "Getting the Forrest source" section references the obsolete
> "Forrest Primer" for specific CVS instructions.  I will take those out and move
> them into the "Contributing" page.
> 
> 
+1 fine with me

Re: 'building forrest' documentation move?

[David Crossley <cr...@indexgeo.com.au>]

Remember that the FAQs link straight to those sections
in "Using Forrest", so it might need some tweaks.

--David

Re: 'building forrest' documentation move?

[David Crossley <cr...@indexgeo.com.au>]

Dave Brondsema wrote:
> ...<snip/>Also, the "Getting the Forrest source" section
> references the obsolete "Forrest Primer" for specific
> CVS instructions.  I will take those out and move them into
> the "Contributing" page.

Excellent idea to clean those sections up.

When i joined Cocoon, i did the same thing - consolidated such
stuff into their Contributing page. When Forrest started, we took
the Cocoon page as a template. Unfortunately the "CVS Precis"
section from the Cocoon page was lost. Anyway, you might like to
look again at that page for ideas.

It is silly that we need to repeat such information. I wonder
if such guidelines should be put into various HowTo documents
in our Community section. If those documents were kept generic,
then they could apply to any project and just be directly linked.

There could be an additional benefit for projects that use Forrest
for their doc production - they would get ready-made HowTo documents.
The 'forrest seed' could perhaps copy them into place and customise
to add project-specific cvs commands.

I am glad that their are some people enthusiastic about the
documentation. All documentation needs continual evolution.

--David