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
