Mailing-List: contact archiva-dev-help@maven.apache.org; run by ezmlm
Precedence: bulk
Reply-To: archiva-dev@maven.apache.org
Received-SPF: neutral (herse.apache.org: local policy)
Mime-Version: 1.0 (Apple Message framework v752.3)
In-Reply-To: <4651C265.70501@apache.org>
References: <4651C265.70501@apache.org>
Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed
Message-Id: <2363FF27-EA8E-4EC7-8F3F-3502F9C05232@apache.org>
Content-Transfer-Encoding: 7bit
From: Brett Porter <brett@apache.org>
Subject: Re: [discussion] archiva-site & version specific documentation.
Date: Tue, 22 May 2007 14:06:05 +1000
To: archiva-dev@maven.apache.org

This spans more than Archiva, but it'd be great to do it "right" here  
and then show it works and apply it outwards to other projects.

On 22/05/2007, at 2:01 AM, Joakim Erdfelt wrote:

> I'd like to make the top level aggregated javadoc be versioned into  
> a neutral (stripped of alpha, beta, rc, SNAPSHOT, etc..) url path,  
> but the actual generated javadoc contain the those stripped  
> identifiers.
>
> So, archiva-0.9 branch (0.9-alpha-3-SNAPSHOT) goes into http:// 
> maven.apache.org/archiva/apidoc/0.9/
> and archiva trunk (1.0-alpha-1-SNAPSHOT) goes into http:// 
> maven.apache.org/archiva/apidoc/1.0/

+1, but instead of stripping the identifier how about we just come  
back and remove the alpha-X versions later? That way we simplify to $ 
{project.version}.

This should also go for the whole "developer site" (ie, everything  
produced by maven site at the top level).

>
> I'd also like to get as many of the concept details into the  
> javadoc, vs the site, just to maintain the version specific nature  
> of the documentation.

The more in the javadoc the better, but I think it needs a versioned  
doc that explains things the javadoc can't, and links out to the  
various pieces to give guidance.

> :: The archiva-site module ::
>
> Ultimately, this module is really archiva version independent.
>
> Should we try to move this module out of the tree into it's own top  
> level?

yep, same level as trunk seems to be the convention if it is  
unversioned. We will always need this.

However, I'm starting to rethink the "version independent" thing. I  
like having one set of evolving documentation that annotates versions  
that things appeared in. However, we are seeing that those versions  
are not being properly annotated, and it's becoming problematic. But  
moving to entirely versioned documentation means that if you write  
things in between releases, you lose the ability to publish it until  
a release (or you revert to the same problem).

So why aren't we going for the best of both worlds?

1) create an unversioned site that contains:
	- front page explanation
	- download pages
	- news, etc.
	- links to related things
	- link to documentation for both latest SVN and latest release

2) versioned documentation (publish each release, as well as latest SVN)
	- full subsite
	- includes documentation for users
	- includes javadoc, source cross reference
	- bundled with distribution
	- still annotate when things were added since sometimes people will  
read documentation for a different version anyway

3) developer documentation (always publish latest)
	- other reports
	- documentation for developers, architecture, etc.

4) contribution area
	- authored in wiki, generated to static files, linked from site  
(http://maven.apache.org/scm/wiki/scm-matrix.html)
	- FAQ, cookbooks
	- always up to date
	- not distributed with binary
	- may be converted into versioned documentation for a future release  
if useful

WDYT?

> Any comments?  Suggestion?  Hate Mail?  Silly Jokes?  Unrelated  
> Arguments?

What did the dolphin say to the whale when he bumped into him? I  
didn't do it on porpoise.

- Brett