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

[Peter Hutterer]

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).

>    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.

>    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?

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.

Cheers,
  Peter