Mailing-List: contact dev-help@forrest.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@forrest.apache.org
Received-SPF: neutral (hermes.apache.org: local policy)
Message-ID: <42394A19.2070306@apache.org>
Date: Thu, 17 Mar 2005 09:12:57 +0000
From: Ross Gardler <rgardler@apache.org>
User-Agent: Mozilla Thunderbird 1.0 (Windows/20041206)
MIME-Version: 1.0
To: Forrest Developers List <dev@forrest.apache.org>
Subject: problem with docs at forrest.apache.org/docs/dev/
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

I just realised a problem with our documentation. Most of us provide 
links to the website when answering questions. Often these links refer 
to the current dev docs which are given an URL of 
http://forrest.apache.org/docs/dev/

Now, when we release the dev version (in this case 0.7) we will 
presumably move the docs to http://forrest.apache.org/docs/0.7/
This will break all the links in the mail archives, well OK, it won't 
actually break them but the URL will no longer point to the document we 
intended.

In some cases the dev version of the document will no longer be relevant 
to the release version (for example if we replace skins with 
forrest:views in 0.8).

I propose that we always publish to the correct version number and 
generate the dev docs with a <warning> at the top of each page like this:

<warning>This is a draft document. It describes functionality that may 
only be present in the current development version of Apache 
Forrest.</warning>

This is easily done with our skinning system, even easier (I believe) 
with forrest:views.

Whilst I'm on this topic, what happens to old documentation for past 
versions. I hope we intend to keep them in the webspace in order to keep 
these mail archive links alive. I'm sure this was discussed but can't 
remember what was decided.

Ross