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: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > -- jvz. Jason van Zyl jason at maven.org http://maven.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
