Mailing-List: contact dev-help@forrest.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@forrest.apache.org
Received-SPF: neutral (asf.osuosl.org: local policy)
Date: Tue, 13 Jun 2006 16:45:16 +1000
From: David Crossley <crossley@apache.org>
To: dev@forrest.apache.org
Subject: Re: Document restructuring - confused
Message-ID: <20060613064516.GD1497@igg.indexgeo.com.au>
References: <448CA14E.3000504@apache.org>
 <529076266.20060612125508@soethe.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <529076266.20060612125508@soethe.net>
User-Agent: Mutt/1.4.2.1i

Ferdinand Soethe wrote:
> Ross Gardler wrote:
> 
> > In the recent restructuring of our document structures I find things 
> > confusing. Maybe it is because I am used to the old structure, but maybe
> > not...

I had exactly the same thoughts. I too wanted to wait and
use it for a bit before commenting.

> You are right. It is confusing because we have happily mixed
> background info, introduction, and step by step instructions in the
> same documents.
> 
> The new structure is an attempt to fix that because it was originally
> intended (afaik) to have seperate instruction (howto) and background
> documents.

That sounds good. So the "howto" documents (don't necessarily
need to be in howto format) should be very concise and point
to the background docs for the full story.

> > For example, why is the locationmap documentation under "whitepapers" 
> > instead of under "customise forrest" or "Extend Forrest"
> 
> Problem is that I have not had the time to rewrite all documents to
> fit the new/old structure so those that mix instruction and background
> may be in the wrong categorie.

This will need to be a gradual process. None of us
have the time to do it.

I imagine that there would be one (sometimes more)
background doc for each topic, e.g. locationmap, and
there would be various how-to docs for the different
situations where locationmap is used. Some howtos
might refer to others as pre-requisites so that we
don't repeat ourselves.

> However, you are right about being used to the old structure because
> it was often just as wrong. People might be looking for general info
> on locationmaps and not find it in whitepapers.
> 
> Proper solution is to rewrite and split documents like that in short
> and concise how-tos with links to longer whitepapers with backgound
> info.
>
> I was in the process of starting that for locationmaps when I had to
> take of a more urgent non-Forrest problem.

Perhaps it would help to add basic how-to docs as
placeholders that simply link to the background docs
or mail threads. Later we can flesh them out. That
might ease the confusion.

Does the term "whitepapers" have the same usage for people
in other countries?

Our Australian dictionary defines "white papers" and
"green papers", both government terminology. There are no
other usage or meaning listed.
[The Macquarie Dictionary, 3rd edition].

* "green paper: proposes policy ... basis for public discussion".

* "white paper: statement of policy, presented to parliament as a
subject for discussion, prior to or accompanying the introduction
of a relevant bill." The bill passes through the lower house, then
the upper house, then enacted.

W3.org seem to have the same use "subject for discussion".

So perhaps we should use a different term. How about
just "Background docs" or "Fundamentals".

I suppose in reality, opensource is a state of
continually evolving whitepapers, never quite enacted.

                ---oOo---

I see another issue. On the "Project" tab we have a
mixture of docs that are procedural stuff for committers
(e.g. howto-release, zone-notes) and others that are
intended for developers/users (e.g. howto-dev and
howto-howto and reporting issues and mail-lists) and
others that apply to both (e.g. subversion-bestpractices).

Now i don't want to completely separate that stuff,
but do want to reduce any distinction. We are all
"developers", just that some of us are also helping
to manage the project.

Perhaps we should rename the Project tab to "Developers"
and re-arrange some items on that tab and the Welcome tab.
I am making some good progress locally. I will send a
screenshot of my proposed layout.

-David