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

[Jordi Polo]

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.
Also most of us will agree on not being rocket science, X is not by any
means a trivial piece of software.
I personally also think that it may not have the best performance in this
world but X gets the work done so not much need arises to collaborate or fix
anything.

I think that most of the people and I mean developers out there have not a
clear idea about X architecture (no further than it uses a protocol and can
be used over the net with local input devices). What are the *proto
thingies? what's each  X* library? How mesa gallium3d dri X mix together? I
don't think the average KDE (for instance) developer can make a better
diagram of how X works than how the Linux kernel works.

So I think that we need documentation and tutorials _really badly_  if new
developers are to be found.

And for maximum visibility, the wiki is the best place.
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?

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


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



On Thu, Jun 12, 2008 at 5:14 PM, Daniel Stone <daniel at fooishbar.org> wrote:

> On Thu, Jun 12, 2008 at 10:49:57AM +0300, Timo Jyrinki wrote:
> > 2008/6/12 Jeremy Huddleston <jeremyhu at freedesktop.org>:
> > > Good, centralized developer documentation is greatly appreciated.
> >
> > Speaking of which, if you have any ideas how to better interlink and
> combine:
> > - http://dri.freedesktop.org/
> > - http://xorg.freedesktop.org/
> > - http://mesa3d.org/
> >
> > ...please don't hesitate updating the wikis. Both DRI and X.Org wikis
> > would benefit if someone would have time to rethink the front page
> > organization by grouping links under different titles and learning
> > moinmoin tables / colouring to bring some more clarity there. Both
> > wikis currently look like the typical wikis, ie. just braindump of
> > links with no thinking about the structure. And yes, I can do
> > something about those myself one day, but anyway there's lots of stuff
> > around to make more beautiful and therefore more accessible.
>
> I don't understand why DRI and Mesa have separate lists and websites,
> tbh, especially given the level of crosstalk.  For the wikis, it should
> be possible to link between them, and I'll try to sort out how to make
> that happen.
>
> If someone has further wiki improvement suggestions on the admin side
> that don't involve MediaWiki (and have a migration path from Moin at
> least as clear as the migration from one Moin release to the next; the
> bar here isn't quite as high as you'd think, though), please let me
> know.
>
> I did start trying to reorganise the xorg wiki at some point, but
> unfortunately only got a small part of the way through before existential
> despair set in.
>
> Cheers,
> Daniel
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (GNU/Linux)
>
> iEYEARECAAYFAkhQ2ugACgkQUVYB1rKAgJRDUwCfZkVXfhqBJhmdmJxmR68B9BDx
> V7cAn0z25mEZflBXYcg9WLgrEVQ4kSzG
> =ywTj
> -----END PGP SIGNATURE-----
>
> _______________________________________________
> xorg mailing list
> xorg at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xorg
>


-- 
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/dbfa6c53/attachment.html>