Wiki like documentation Was: Re: Wrapping up 7.4 (finally)

[Jordi Polo]

Resend, damn gmail reply only behaviour

On Thu, Jun 12, 2008 at 8:17 PM, Peter Hutterer <peter at cs.unisa.edu.au>
wrote:

> On Thu, Jun 12, 2008 at 07:42:48PM +0900, Jordi Polo wrote:
> >    We are mixing at least 3 threads on the Wrapping up 7.4 thread. I fear
> >    that the Wiki discussion will be lost so I start this thread.
> >    I'd also tried to understand current X as I was interested in the new
> >    MPX functionality.  I found that currently the documentation is
> scarce,
> >    bad and/or outdated. I think most of us will agree on that.
>
> actually, we need to differ between how to document what.
> For example, MPX has the protocol specifications documented and the
> client-side library calls. This is true for many of the "external APIs".
>
> The protocol specs and man pages will remain a cornerstone in API
> documentation and should not be superseeded by a wiki.
> the wiki will be ideal for fast-moving documentation though (internal APIs,
> concept descriptions and howtos).
>

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.



> >    First, about the wiki engine, Daniel asked for a Moin replacement.
> What
> >    about Trac? (http://trac.edgewall.org/ ) it is basically the same
> >    syntax than Moin moin, it integrates a bug tracking system (what I
> >    don't know if it is a good idea)  and a lot of plugins
> >    (http://trac-hacks.org/). It is moin moin so horrible to be replaced?
> >    Then is not mediawiki the most beatiful wiki engine out there?
>
> I am hesitant of replacing a working system to get something started. The
> wiki
> already has many pages that only need cleaning up and restructuring. If we
> actually hit the limits of the current system, then replacing becomes an
> option.  But we should _not_ do it because we don't like the looks, or the
> fact that other systems may do it better.
>

Well, Daniel suggested the replacement. I suggested Trac and Mediawiki as
those are the systems I have administrated myself in the past.
Anyway it should be useful to know what problems it exists with Moin Moin so
we can look for a better solution (if available).




>
> >    Second, about the wiki contents. I think we can establish a wiki team,
> >    Reece Dunn seemed interested and I am also interested in helping here.
> >    The wiki team will unify the wikis and with the help of the mailing
> >    list decide the general structure of the documentation on the wiki.
>
> The danger you will run into with assigning a team is that it takes
> responsibility _away_ from those that are not in the team. What I mean with
> that is: If something is broken, I may fix it. If there's a team dedicated
> to
> fixing it, then why should I do it, the team knows more and can do it much
> better than me?
>

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.
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.
 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.
Anyway, if I am the only one that think it is a good idea, a team of one is
nosense ...



> A team can coordinate things and this may become necessary in the future.
> For
> now, I suggest not trying to overorganise things and go one step at a time.
>
> >    They (or we) will work on filling the contents and keep a thumb on the
> >    developers' ribs when the need for more specific information is
> needed.
>
> ACK, fully agree. I know that I often do things after the third email sent
> to
> me.
>
> >    Also and as a side note, I would say that a good way to attract
> >    developers is breaking things. How difficult would it be to include
> >    beta versions on the current release process? There are developers
> that
> >    will not try nightly builds but will try beta versions if it works
> >    reasonablely even if it breaks on a lot of common cases and those
> >    developers are the same that start with some patches to make it work,
> >    continue with some more patches to make it work better ...
>
> I believe some distributions do include git version of the server.
>
> Don't get me wrong, I'm not trying to put a damper on your efforts. But I
> have
> seen in the past that talking about a project and starting it is much more
> exciting that the actual gruntwork the project entails. I suggest starting
> with the gruntwork and leaving the excitenment for later.


You are definitely right.

In this first approximation I would like to discuss:
- The wiki engine is changed or no.
- Will API documentation have a web form? If so, what are the alternatives?
- Will protocol documentation have a web form? If so, alternatives?
-  It is useful to have the info on  http://dri.freedesktop.org/ as a Wiki
or can we create webpages with it and add it to  http://mesa3d.org/ ?
- I can not access bugs.freedesktop.org , there is a category for
documentation bugs for X.org?

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.

BTW, freedesktop goes terrible slow for me today.




-- 
Jordi Polo Carres
NLP laboratory - NAIST
http://www.bahasara.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.x.org/archives/xorg/attachments/20080612/cc86d457/attachment.html>