Ok, this is think outside the box time... I like Thomas' comments on
centralizing documentation. I really, really like Thomas' comments on
centralizing documentation. However, I think the logistics may be
off. I'm thinking of the documentation problem as similar to the
build problem.
Before there was maven, users had to go from site to site downloading
jars and collecting them into a useful, coherent code base every time
they wanted to build because a bunch of different groups contributed a
bunch of small, but useful artifacts. That got fixed. Unfortunately,
we're now finding that users are going from site to site browsing
documentation and collecting it into a useful, coherent knowledge base
every time they want to understand something because a bunch of
different groups contributed a bunch of small, but useful bits of
documentation.
So, here's what I propose: Lets create a repository for
documentation. The docs will exist within the projects, as they do
now, and we'll use an APT/Wiki hybrid that allows for linking between
projects (e.g. [[groupId:artifactID]]) and documents (e.g. guides,
javadocs, etc.) within those projects. That way, there's quality
control because the docs have to be committed, we avoid the
unrealistic
make-a-giant-book-that-somebody's-going-to-be-in-charge-of-because-I-don't-want-to
plan, and we get the centralized feel with out having to duplicate the
little bits of usefulness that already exist.
Obviously, there will be a lot of gaps, broken links, etc. in the
early stages, but I don't think that it would be any worse than with a
typical wiki. There may be a slower turnaround in updates, but that
might be balanced out by the fact that current documentation could be
reused. Later, if we want something more interactive there could be a
tool for generating and submitting documentation patches via this
online repository.
So that's my little bit of brainstorming. There are obvious issues
like hosting, but for now I dare to dream... :-) Thoughts?
On 11/2/06, Thomas Van de Velde <[EMAIL PROTECTED]> wrote:
The problem, as I see it, is that the documentation is fragmented.
Unlike
Hibernate and Spring, which provide a single reference manual which is
kept
up to date with every release, Maven documentation is spread all over the
place (wiki, generated sites, better builds with Maven, etc.). The
problem
gets worse with the isolated documentation for plugins. Plugins may make
sense from a technical point of view, but an end-user can care less about
plugin seperation from the core. They want to see consistent
documentation
for all features, whether those are provided by the core or by
plugins. By
forcing ALL documentation to be centralized (e.g. in a reference manual),
you naturally get better consistency and logical flow between the
different
pieces (Instead of a bunch of isolated how-to's and plugin pages).
What a
mess Spring's documentation would be if they'd start generating
seperate web
sites for each framework they integrate with!
Users have been complaining for years about Maven documentation and I
agree
with those who say that this is a break on wider Maven adoption. As an
experienced user, I have no trouble finding what I am looking for but
I can
tell you from my experience dealing with many new users, that the
newbies have big trouble finding their way through the documentation
jungle. More than once have I seen projects giving up just because they
didn't find an easy way to get started. This is highly regrettable as
they
are missing out on a great tool!
So my recommendation would be:
1) Centralize documentation (prefereably on a wiki so that users can
comment
on questions). Why not take the Merger book as a starting point?
2) Update documentation with every release.
An undocumented feature is an unexisting feature.
Thomas
On 11/2/06, Adam Hardy <[EMAIL PROTECTED]> wrote:
>
> Wendy Smoak on 02/11/06 22:34, wrote:
> > On 11/2/06, Sebastien Brunot <[EMAIL PROTECTED]> wrote:
> >
> >> What I meant by "it" was the comment mechanism.
> >
> > Right... it doesn't exist yet, we need to design it.
>
> The comment mechanism can be a wiki where the public can only add at
the
> bottom
> of the page, and the contributors are the ones who sort out the
wheat from
> the
> chaff occasionally to enhance each page from its comments.
>
> > Earlier, I asked, "Any ideas on how to present that as an option?
>
> It's done at mysql[1], php and someone said Hibernate and I think
Drupal.
> But my
> quick investigation there didn't show anything. Check out mysql though.
> Perhaps
> their documentation publishing framework is OS.
>
> > What would the menu link be called? How should the pages on the wiki
> > be organized?"
>
> I think the whole maven documentation website should be
wiki-commentated
> (is
> that the correct verb here??)
>
> So each plugin remains as it is except the wiki-commentary can be
appended
> to
> the bottom of every page.
>
> I think that any plugin that makes it onto repo.maven.org should get
its
> docs
> site on the website too, at least for the releases.
>
> regards
> Adam
>
> [1] http://dev.mysql.com/doc/refman/5.0/en/linux-rpm.html
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>
>
