You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@maven.apache.org by Alexander Hars <do...@inventivio.com> on 2005/11/11 10:42:58 UTC
Documentation -- making better use of the wiki
Hi,
I have been using Maven2 for two weeks and am very impressed by all the
great features.
However, the learning curve is steep and it is often very difficult to
find certain answers (I often need to
to look at the source code to find them). Whenever I find an answer to a
question, I alone have learned.
Others don't profit. I would be quite willing to submit an answer to
Maven2 for inclusion into the guides. But that takes
quite a bit of time (...going into CVS, downloading the apt file,
modifying it, testing it, submitting it to someone for posting
to the CVS etc.). I did that once, but we can't expect big progress in
the documentation to occur this way.
The only solution that does not overload the developers (who put in so
much time already anyhow), is to make better use
of the wiki because everybody can contribute and increase our cumulated
knowledge. But just providing the wiki as
it is now (http://wiki.apache.org/maven/Maven2Info) does not work. There
is almost nothing there, almost nobody
goes to it, therefore few people add anything either.
There are two practical ways in which we could make better use of the wiki:
a) provide a prominent link from the Maven2 documentation (guides,
miniguides, references, etc.) to a related wiki
page. Anyone who has some insight to add to the documentation can place
it there; anyone who has not found the
answer in the standard documentation can easily check whether there is
more information in the wiki. From time
to time someone can integrate the bulk of good insights from the wiki
back into the documentation.
b) put most of the documentation into the wiki. In my opinion this is
the ideal case, because it would reduce the
load on the developers for providing the documentation and there would
be a single documentation mechanism.
But it is probably not practical because the Maven Wiki is not based on
the .apt format and integration with the
maven site generation mechanism may be difficult.
Option a) is very easy to do. We would only need to create associated
wiki pages and insert a link to the wiki
page from the original documentation. I am sure that we could greatly
expand the Maven-related knowledge
this way.
I certainly would be willing to work on the necessary changes to get
this rolling if you think this is a good idea.
- Alexander Hars
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Documentation -- making better use of the wiki
Posted by Jason van Zyl <ja...@maven.org>.
Hi,
In order to make it easier for users to contribute documentation I have
setup a space for those users who want to contribute documentation:
http://docs.codehaus.org/display/MAVENUSER/Home
If you sign yourself up and ping me I will give you access to the space.
This way you can start writing content now and we'll be able to extract
it once we finish our Confluence tools.
Using Confluence is easier for us because that's what we've been using
for anything related to Maven 2.x so far.
I hope this helps.
--
jvz.
Jason van Zyl
jason at maven.org
http://maven.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Documentation -- making better use of the wiki
Posted by Anuerin Diaz <ra...@gmail.com>.
this idea has been going around. the maven developers rely on JIRA for
the prioritization of their task so if you really want this proposal
to be accepted then you can vote on this task
http://jira.codehaus.org/browse/MNG-1521
it is a placemarker JIRA task containing Alexander's suggestion below.
ciao!
On 11/11/05, Alexander Hars <do...@inventivio.com> wrote:
> Hi,
>
> I have been using Maven2 for two weeks and am very impressed by all the
> great features.
>
> However, the learning curve is steep and it is often very difficult to
> find certain answers (I often need to
> to look at the source code to find them). Whenever I find an answer to a
> question, I alone have learned.
> Others don't profit. I would be quite willing to submit an answer to
> Maven2 for inclusion into the guides. But that takes
> quite a bit of time (...going into CVS, downloading the apt file,
> modifying it, testing it, submitting it to someone for posting
> to the CVS etc.). I did that once, but we can't expect big progress in
> the documentation to occur this way.
>
> The only solution that does not overload the developers (who put in so
> much time already anyhow), is to make better use
> of the wiki because everybody can contribute and increase our cumulated
> knowledge. But just providing the wiki as
> it is now (http://wiki.apache.org/maven/Maven2Info) does not work. There
> is almost nothing there, almost nobody
> goes to it, therefore few people add anything either.
>
> There are two practical ways in which we could make better use of the wiki:
>
> a) provide a prominent link from the Maven2 documentation (guides,
> miniguides, references, etc.) to a related wiki
> page. Anyone who has some insight to add to the documentation can place
> it there; anyone who has not found the
> answer in the standard documentation can easily check whether there is
> more information in the wiki. From time
> to time someone can integrate the bulk of good insights from the wiki
> back into the documentation.
>
> b) put most of the documentation into the wiki. In my opinion this is
> the ideal case, because it would reduce the
> load on the developers for providing the documentation and there would
> be a single documentation mechanism.
> But it is probably not practical because the Maven Wiki is not based on
> the .apt format and integration with the
> maven site generation mechanism may be difficult.
>
> Option a) is very easy to do. We would only need to create associated
> wiki pages and insert a link to the wiki
> page from the original documentation. I am sure that we could greatly
> expand the Maven-related knowledge
> this way.
>
> I certainly would be willing to work on the necessary changes to get
> this rolling if you think this is a good idea.
>
> - Alexander Hars
>
>
>
>
>
>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
--
"Programming, an artform that fights back"
Anuerin G. Diaz
Registered Linux User #246176
Friendly Linux Board @ http://mandrivausers.org/index.php
http://capsule.ramfree17.org , when you absolutely have nothing else
better to do
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Documentation -- making better use of the wiki
Posted by Jason van Zyl <ja...@maven.org>.
On Fri, 2005-11-11 at 10:42 +0100, Alexander Hars wrote:
> Hi,
>
> I have been using Maven2 for two weeks and am very impressed by all the
> great features.
>
> However, the learning curve is steep and it is often very difficult to
> find certain answers (I often need to
> to look at the source code to find them). Whenever I find an answer to a
> question, I alone have learned.
> Others don't profit. I would be quite willing to submit an answer to
> Maven2 for inclusion into the guides. But that takes
> quite a bit of time (...going into CVS, downloading the apt file,
> modifying it, testing it, submitting it to someone for posting
> to the CVS etc.).
That what actually saves us time. Being able to easily integrate it into
what we have now. I'm not saying this ideal, but using a wiki isn't
going to magically make this process better.
> I did that once, but we can't expect big progress in
> the documentation to occur this way.
In your case, the patch went in very quickly and was published but we
didn't redirect the old m2 site to its new location and you didn't see
it but it was processed pretty quickly. So, as the person who has done
most of the doco for m2 I can say that I love patches.
> The only solution that does not overload the developers (who put in so
> much time already anyhow), is to make better use
> of the wiki because everybody can contribute and increase our cumulated
> knowledge. But just providing the wiki as
> it is now (http://wiki.apache.org/maven/Maven2Info) does not work. There
> is almost nothing there, almost nobody
> goes to it, therefore few people add anything either.
I encourage users to place content in the wiki and it will get processed
when we have time but patches are better if you want the material to
make it into the main site.
> There are two practical ways in which we could make better use of the wiki:
>
> a) provide a prominent link from the Maven2 documentation (guides,
> miniguides, references, etc.) to a related wiki
> page. Anyone who has some insight to add to the documentation can place
> it there; anyone who has not found the
> answer in the standard documentation can easily check whether there is
> more information in the wiki. From time
> to time someone can integrate the bulk of good insights from the wiki
> back into the documentation.
Unfortunately we have had problems with the Apache wiki being defaced so
we stopped using it.
> b) put most of the documentation into the wiki. In my opinion this is
> the ideal case, because it would reduce the
> load on the developers for providing the documentation and there would
> be a single documentation mechanism.
It does not reduce the load on developers because having everything in
the wiki does not make for good documentation. I'm not saying what we
have is stellar but again the wiki is not a panacea.
Ideally what we would like is an APT-based wiki with staging/editing
capabilities but until that happens having to make a patch is a pretty
good vetting process for content.
> But it is probably not practical because the Maven Wiki is not based on
> the .apt format and integration with the
> maven site generation mechanism may be difficult.
Exactly.
Now I haven't looked at the Apache Wiki in a while but what is possible
is to create a doxia parser for moin moin and then we could more easily
integrate it. If someone did that I would probably look at the wiki, but
otherwise it just creates more work having to convert it.
We are working on some tools to pull content out of Confluence and
integrate it with the site so what we may also be able to do is setup a
space for Maven users to work on content and then we can automatically
pull stuff out of Confluence. We use Confluence and I would prefer not
start using another wiki until we get an APT-based wiki.
We would probably also need people to ask for access because leaving the
wiki wide open has caused problems in the past.
> Option a) is very easy to do. We would only need to create associated
> wiki pages and insert a link to the wiki
> page from the original documentation. I am sure that we could greatly
> expand the Maven-related knowledge
> this way.
I truly admire your enthusiasm and I will work with you if you want to
try and come up with a solution but in my experience the total ad hoc
solution doesn't work.
> I certainly would be willing to work on the necessary changes to get
> this rolling if you think this is a good idea.
Helping to work on the confluence tools would probably be the best place
to start, but in the mean time for people who want to start creating
content I can create a space on Confluence and anyone who wants access
just needs to ask and I will set you up asap if you want to write
content.
You can actually sign up yourself and then I can turn on your access and
you can write all you like!
I will set something up now.
> - Alexander Hars
>
>
>
>
>
>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
--
jvz.
Jason van Zyl
jason at maven.org
http://maven.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Documentation -- making better use of the wiki
Posted by Ralph Pöllath <li...@poellath.org>.
+1
Cheers,
-Ralph.
On 11.11.2005, at 11:01, David Sag wrote:
> +1
>
> Kind regards,
> Dave Sag
>
> Alexander Hars <do...@inventivio.com> wrote on 11-11-2005
> 10:42:58:
>> Hi,
>>
>> I have been using Maven2 for two weeks and am very impressed by
>> all the
>> great features.
>>
>> However, the learning curve is steep and it is often very
>> difficult to
>> find certain answers (I often need to
>> to look at the source code to find them). Whenever I find an
>> answer to a
>
>> question, I alone have learned.
>> Others don't profit. I would be quite willing to submit an answer to
>> Maven2 for inclusion into the guides. But that takes
>> quite a bit of time (...going into CVS, downloading the apt file,
>> modifying it, testing it, submitting it to someone for posting
>> to the CVS etc.). I did that once, but we can't expect big
>> progress in
>> the documentation to occur this way.
>>
>> The only solution that does not overload the developers (who put
>> in so
>> much time already anyhow), is to make better use
>> of the wiki because everybody can contribute and increase our
>> cumulated
>> knowledge. But just providing the wiki as
>> it is now (http://wiki.apache.org/maven/Maven2Info) does not work.
>> There
>
>> is almost nothing there, almost nobody
>> goes to it, therefore few people add anything either.
>>
>> There are two practical ways in which we could make better use of the
> wiki:
>>
>> a) provide a prominent link from the Maven2 documentation (guides,
>> miniguides, references, etc.) to a related wiki
>> page. Anyone who has some insight to add to the documentation can
>> place
>> it there; anyone who has not found the
>> answer in the standard documentation can easily check whether
>> there is
>> more information in the wiki. From time
>> to time someone can integrate the bulk of good insights from the wiki
>> back into the documentation.
>>
>> b) put most of the documentation into the wiki. In my opinion this is
>> the ideal case, because it would reduce the
>> load on the developers for providing the documentation and there
>> would
>> be a single documentation mechanism.
>> But it is probably not practical because the Maven Wiki is not
>> based on
>> the .apt format and integration with the
>> maven site generation mechanism may be difficult.
>>
>> Option a) is very easy to do. We would only need to create associated
>> wiki pages and insert a link to the wiki
>> page from the original documentation. I am sure that we could greatly
>> expand the Maven-related knowledge
>> this way.
>>
>> I certainly would be willing to work on the necessary changes to get
>> this rolling if you think this is a good idea.
>>
>> - Alexander Hars
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Documentation -- making better use of the wiki
Posted by David Sag <ds...@epo.org>.
+1
Kind regards,
Dave Sag
Alexander Hars <do...@inventivio.com> wrote on 11-11-2005 10:42:58:
> Hi,
>
> I have been using Maven2 for two weeks and am very impressed by all the
> great features.
>
> However, the learning curve is steep and it is often very difficult to
> find certain answers (I often need to
> to look at the source code to find them). Whenever I find an answer to a
> question, I alone have learned.
> Others don't profit. I would be quite willing to submit an answer to
> Maven2 for inclusion into the guides. But that takes
> quite a bit of time (...going into CVS, downloading the apt file,
> modifying it, testing it, submitting it to someone for posting
> to the CVS etc.). I did that once, but we can't expect big progress in
> the documentation to occur this way.
>
> The only solution that does not overload the developers (who put in so
> much time already anyhow), is to make better use
> of the wiki because everybody can contribute and increase our cumulated
> knowledge. But just providing the wiki as
> it is now (http://wiki.apache.org/maven/Maven2Info) does not work. There
> is almost nothing there, almost nobody
> goes to it, therefore few people add anything either.
>
> There are two practical ways in which we could make better use of the
wiki:
>
> a) provide a prominent link from the Maven2 documentation (guides,
> miniguides, references, etc.) to a related wiki
> page. Anyone who has some insight to add to the documentation can place
> it there; anyone who has not found the
> answer in the standard documentation can easily check whether there is
> more information in the wiki. From time
> to time someone can integrate the bulk of good insights from the wiki
> back into the documentation.
>
> b) put most of the documentation into the wiki. In my opinion this is
> the ideal case, because it would reduce the
> load on the developers for providing the documentation and there would
> be a single documentation mechanism.
> But it is probably not practical because the Maven Wiki is not based on
> the .apt format and integration with the
> maven site generation mechanism may be difficult.
>
> Option a) is very easy to do. We would only need to create associated
> wiki pages and insert a link to the wiki
> page from the original documentation. I am sure that we could greatly
> expand the Maven-related knowledge
> this way.
>
> I certainly would be willing to work on the necessary changes to get
> this rolling if you think this is a good idea.
>
> - Alexander Hars
>
>
>
>
>
>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>