I think the first thing we need to do is inventory and evaluate all existing documentation. It is not only important to determine what documentation exists but also how relevent it is and whether it needs to be updated or removed from the website. Once we figure out what we have we can then figure out what we need and people can decide what they want to do. I know there are people who don't mind writing documentation if they can get answers to questions when they need it. For others, digging through code is what they do best so combined they may be able to create some useful documentation. I don't think we can expect Daryll, Paul, or the other core DRI developers to write the documentation but if we could get some high level guidance on what is lacking or out of date in existing documentation that would be very useful. To bring DRI to critical mass where things just happen like the Linux kernel will take a group effort so everyone needs to be on the same page.
Personally, I am mostly concerned with developer documentation as I expect that the uesr documentation is more up to date. So with that in mind I ask the following. Could the DRI experts offer some feedback on the relevence and usefullness of the following documents. Are the reasonably up to date? Are they moderately up to date? Are they out of date and not extremely useful with respect to the current DRI artitecture? 1. Introduction to the Direct Rendering Infrastructure - Brian Paul, August 2000 http://dri.sourceforge.net/doc/DRIintro.html 2. Dri term glossary. http://dri.sourceforge.net/doc/glossary.html I suspect this doesn't need to be changed but is there anything that should be added? 3. Data flow diagram http://dri.sourceforge.net/doc/data_flow.jpg 4. Control flow diagram http://dri.sourceforge.net/doc/control_flow.jpg 5. A Multipipe Direct Rendering Artitecture for 3D. Jens Owen, Kevin E. Martin. September 1998 http://dri.sourceforge.net/doc/design_high_level.html 6. Direct Rendering Infrastructure, Low-Level Design Document. Kevin E. Martin, Rickard E. Faith, Jens Owen, Allen Akin http://dri.sourceforge.net/doc/design_low_level.html 7. The Direct Rendering Manager: Kernel Suport for the Direct Rendering Infrastrucure. Rickard E. Faith http://dri.sourceforge.net/doc/design_high_level.html 8. Hardware Locking for the Direct Rendering Infrastructure. Rickard E. Faith, Jens Owen, Kevin E. Martin http://dri.sourceforge.net/doc/hardware_locking_low_level.html 9. A Security Analysis of the Direct Rendering Infrastructure. Rickard E. Faith, Kevin E. Martin http://dri.sourceforge.net/doc/security_low_level.html 10. DRI Extension for supporting Direct Rendering Protocol Specification. Jens Owen, Kevin Martin http://dri.sourceforge.net/doc/dri_extensions_low_level.txt I believe those are all the important developer and design documents on the DRI website. Do any others exist anywhere that might help developers? I think the first step might be to clean up the high level design documents so new developers can quickly see how all the pieces of DRI fit together and how they are interdependent on each other as well as with XFree86, Mesa and the kernel. From there we can develop more detailed documentation on each part of DRI and the major functions used in each part (this documentation can be done through extracing in code documentation as others have suggested). When all is done I would like to have it so that if, for instance, someone is having a problem getting AGP to work with a Graphics card ABC and motherboard XYZ and want to fix it they can quickly browse over the high level documentation which will explain to them the DRI artitecture and point them to the appropriate place(s) in the source code where AGP related stuff is handled. Again, I don't think we can demand that Daryll, Paul, Jens, and the other DRI experts sit down and write documentation or spend 8 hours a week in IRC chats but if we can get them to point out what is wrong with current documentation and share some of their knowledge with the rest of us hopefully the rest of us can take the ball and run with it. _________________________________________________________________ Send and receive Hotmail on your mobile device: http://mobile.msn.com _______________________________________________ Dri-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/dri-devel
