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

[Jesse Barnes]

On Thursday, June 12, 2008 7:26 am Jordi Polo wrote:
> 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?

Personally, I'd like to see API documentation in man page form.  Several 
packages are missing this at the moment and that could be remedied fairly 
easily (i.e. you don't have to have deep architectural knowledge to document 
many libraries).

> - Will protocol documentation have a web form? If so, alternatives?

I think XCB would be a good reference here, iirc they have protocol 
descriptions they use to generate code & documentation?

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

To me, the priorities would be:
  1) man page documentation for external APIs
  2) good info on how to build the latest bits (and how they fit together)
  3) architectural & API documentation for internal stuff to help new
     developers get up to speed (like X's DESIGN document)

Writing up some DRM documentation for review is on my TODO list for this month 
(has been for awhile actually); I hope to have something by next week or so 
to post and get feedback on (falls into bucket #3 unless I also get around to 
writing some libdrm man pages).

Thanks,
Jesse