<br>Resend, damn gmail reply only behaviour<br><br><div class="gmail_quote"><div class="Ih2E3d">On Thu, Jun 12, 2008 at 8:17 PM, Peter Hutterer <<a href="mailto:peter@cs.unisa.edu.au" target="_blank">peter@cs.unisa.edu.au</a>> wrote:<br> <blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"> <div>On Thu, Jun 12, 2008 at 07:42:48PM +0900, Jordi Polo wrote:<br> </div><div>> We are mixing at least 3 threads on the Wrapping up 7.4 thread. I fear<br> > that the Wiki discussion will be lost so I start this thread.<br> > I'd also tried to understand current X as I was interested in the new<br> > MPX functionality. I found that currently the documentation is scarce,<br> > bad and/or outdated. I think most of us will agree on that.<br> <br> </div>actually, we need to differ between how to document what.<br> For example, MPX has the protocol specifications documented and the<br> client-side library calls. This is true for many of the "external APIs".<br> <br> The protocol specs and man pages will remain a cornerstone in API<br> documentation and should not be superseeded by a wiki.<br> the wiki will be ideal for fast-moving documentation though (internal APIs,<br> concept descriptions and howtos).<br> </blockquote></div><div><br>In fact what I wanted to say is that because of MPX I got interested in X and looking for X documentation I found it lacking. <br> <br><br></div><div class="Ih2E3d"><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"> <div><br> > First, about the wiki engine, Daniel asked for a Moin replacement. What<br> > about Trac? (<a href="http://trac.edgewall.org/" target="_blank">http://trac.edgewall.org/</a> ) it is basically the same<br> > syntax than Moin moin, it integrates a bug tracking system (what I<br> > don't know if it is a good idea) and a lot of plugins<br> > (<a href="http://trac-hacks.org/" target="_blank">http://trac-hacks.org/</a>). It is moin moin so horrible to be replaced?<br> > Then is not mediawiki the most beatiful wiki engine out there?<br> <br> </div>I am hesitant of replacing a working system to get something started. The wiki<br> already has many pages that only need cleaning up and restructuring. If we<br> actually hit the limits of the current system, then replacing becomes an<br> option. But we should _not_ do it because we don't like the looks, or the<br> fact that other systems may do it better.<br> </blockquote></div><div><br>Well, Daniel suggested the replacement. I suggested Trac and Mediawiki as those are the systems I have administrated myself in the past.<br>Anyway it should be useful to know what problems it exists with Moin Moin so we can look for a better solution (if available).<br> <br><br> </div><div class="Ih2E3d"><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div><br> > Second, about the wiki contents. I think we can establish a wiki team,<br> > Reece Dunn seemed interested and I am also interested in helping here.<br> > The wiki team will unify the wikis and with the help of the mailing<br> > list decide the general structure of the documentation on the wiki.<br> <br> </div>The danger you will run into with assigning a team is that it takes<br> responsibility _away_ from those that are not in the team. What I mean with<br> that is: If something is broken, I may fix it. If there's a team dedicated to<br> fixing it, then why should I do it, the team knows more and can do it much<br> better than me?<br> </blockquote></div><div><br>Wiki editing is not the funniest stuff in the world. I think that developers will tend to ignore it. The same goes for other documentation processes. <br>The idea of the team is a way to press a number of people to work on specific issues of documentation, documentation bugs will go to them, decide how the wiki front page will look, etc.<br> I guess the same thing can done without a team but I think that knowing there is someone out there can encourage bug reporting, giving ideas for documentation, etc.<br>Anyway, if I am the only one that think it is a good idea, a team of one is nosense ...<br> <br><br></div><div class="Ih2E3d"><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><br> A team can coordinate things and this may become necessary in the future. For<br> now, I suggest not trying to overorganise things and go one step at a time.<br> <div><br> > They (or we) will work on filling the contents and keep a thumb on the<br> > developers' ribs when the need for more specific information is needed.<br> <br> </div>ACK, fully agree. I know that I often do things after the third email sent to<br> me.<br> <div><br> > Also and as a side note, I would say that a good way to attract<br> > developers is breaking things. How difficult would it be to include<br> > beta versions on the current release process? There are developers that<br> > will not try nightly builds but will try beta versions if it works<br> > reasonablely even if it breaks on a lot of common cases and those<br> > developers are the same that start with some patches to make it work,<br> > continue with some more patches to make it work better ...<br> <br> </div>I believe some distributions do include git version of the server.<br> <br> Don't get me wrong, I'm not trying to put a damper on your efforts. But I have<br> seen in the past that talking about a project and starting it is much more<br> exciting that the actual gruntwork the project entails. I suggest starting<br> with the gruntwork and leaving the excitenment for later.</blockquote></div><div><br>You are definitely right.<br><br>In this first approximation I would like to discuss:<br>- The wiki engine is changed or no.<br>- Will API documentation have a web form? If so, what are the alternatives?<br> - Will protocol documentation have a web form? If so, alternatives?<br>- It is useful to have the info on <a href="http://dri.freedesktop.org/" target="_blank">http://dri.freedesktop.org/</a> as a Wiki or can we create webpages with it and add it to <a href="http://mesa3d.org/" target="_blank">http://mesa3d.org/</a> ?<br> - I can not access <a href="http://bugs.freedesktop.org/" target="_blank">bugs.freedesktop.org</a> , there is a category for documentation bugs for X.org?<br><br>Mainly I want to draw a big picture of TODO work on the documentation front. Other ideas (not specifics like howto about ... but more general like stated above) are welcomed. <br> <br>BTW, freedesktop goes terrible slow for me today. <br> </div></div><br><br clear="all"><br>-- <br>Jordi Polo Carres<br>NLP laboratory - NAIST<br><a href="http://www.bahasara.org">http://www.bahasara.org</a><br>