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
