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

[Daniel Stone]

Hi,

On Thu, Jun 12, 2008 at 07:42:48PM +0900, Jordi Polo wrote:
> 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.

You won't find anyone disagreeing with you: the problem of late has been
that we've been so flat-out catching up with what needs to be done to
have even basic functionality, particularly with drivers (between Intel,
AMD and Nouveau drivers, there's been an amazing chunk of spent by Eric,
Keith, Jesse, Alex, Dave, Jerome, myself, Stephane, and everyone else),
that we haven't been focussing on documentation.

I think now we're finally at a point where we can take a breather for a
month or two and start documenting what we have/want.

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

With my fd.o admin hat on, we're just not running a PHP wiki, sorry.
Yes, it's the most widely deployed, probably has the syntax, and it's
probably the easiest of all of them to make it look nice (yeesh, English
is failing me today).

My main problem with Trac is that it integrates its own BTS and
integrates everything with SVN (does it support git?).  The BTS on its
own is just one more thing to migrate.

Given the 'why fix something external when you could write a worse
replacement?' guiding principle of X, I've been thinking of writing a
wiki using Django.  Honestly, I don't think it's the worst idea ever.

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

That'd be awesome.  For the moment, it'd be fine to use xorg@, but when
(maybe I'm being a little hopeful) the traffic starts overwhelming devel
stuff, we can create xorg-docs at .

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

Releases are not our strong point.  Every release starts with the
honourable intention of regular alpha/beta snapshots, but that rapidly
evaporates after a while.  Speaking for myself, it's simply because if I
was doing _anything_ with X, it'd be trying to fix critical bugs or
infrastructure, rather than dumping out a release; doing the latter
would just inspire guilt.  I can't speak for ajax, but I don't suppose
1.5 was dissimilar.

Maybe this is something we need to get better at ourselves, or maybe we
just need multiple people willing to cut betas and shove them out.
Either way, 1.6: this time for sure.

Cheers,
Daniel
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: Digital signature
URL: <http://lists.x.org/archives/xorg/attachments/20080612/d1e09f45/attachment.pgp>