archiva-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Brett Porter <br...@apache.org>
Subject Re: [discussion] archiva-site & version specific documentation.
Date Fri, 25 May 2007 06:00:15 GMT
Joakim,

What do you think? I think the discussion has kind of moved over to  
dev@ now anyway, but since you werw asking for feedback ust wanted to  
check what you thought.

- Brett

On 22/05/2007, at 2:06 PM, Brett Porter wrote:

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

Mime
View raw message