archiva-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joakim Erdfelt <joa...@erdfelt.com>
Subject Re: [discussion] archiva-site & version specific documentation.
Date Thu, 31 May 2007 16:48:46 GMT
To be frank, I haven't payed attention to maven-dev's discussion, as it 
seems focused on plugin docs.

I'm too focused on fixing JIRA's, and preparing for 1.0-alpha-1 to worry 
about documentation on maven.

-Joakim

Brett Porter wrote:
> 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