You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@archiva.apache.org by Joakim Erdfelt <jo...@apache.org> on 2007/05/21 18:01:41 UTC
[discussion] archiva-site & version specific documentation.
I'd like to get a discussion going on how to tackle the documentation
present on the site.
:: Javadoc distribution and role ::
I'm a firm believer that the javadoc for a project should be versioned
and always available, even for back versions.
If we use http://jakarta.apache.org/commons/collections/ as a good
example of this, you'll see that javadoc for version 2.1.1, 3.2, and
SVN-Latest are all available online.
Course, this makes more sense with a library that gets reused, than a
webapp.
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/
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 per module javadoc.jar files should still be generated and deployed
for the benefit of the IDE users.
:: 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?
Or should we just treat the one in trunk as the 'current' version that
exists on http://maven.apache.org/archiva/ ?
Should we have version specific documentation sections on the left hand
navigation menu?
Or should we have basic menu options, with disambiguation portal pages
to the specific versions?
Some documentation is not version specific, database setup, web
container setup, purpose, configuration (to a limited degree), getting
started, FAQ, etc...
We can reference/link the latest released javadoc section for the
details on that version.
Any comments? Suggestion? Hate Mail? Silly Jokes? Unrelated Arguments?
--
- Joakim Erdfelt
joakime@apache.org
joakime@codehaus.org
Archiva Developer
Alpaca Founding Member
Re: [discussion] archiva-site & version specific documentation.
Posted by Joakim Erdfelt <jo...@erdfelt.com>.
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
>>
Re: [discussion] archiva-site & version specific documentation.
Posted by Brett Porter <br...@apache.org>.
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
>
Re: [discussion] archiva-site & version specific documentation.
Posted by Brett Porter <br...@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