On 05/27/11 04:43 PM, David Jackson wrote: > This advice is valid for all software projects. if you want people to help > develop software, document the software code with documentation. Explain how > the > parts of the software fit together, how the code operates, explain what the > different parts do, document functions and variables and what each of those > do. > Explain the processes involved with several of the code paths, such as the > code > path followed at startup, and when a message or event is recieved, and so. > provide documentation that will allow a person with only a basic understanding > of C or Python or other language used to become an expert in the software, > without having to do detective work to try to backengineer how the software > works. With software, it can take months to figure out how complex software > work > by looking at source code, with good documentation this can be reduced to days > or weeks.
The current developers have mostly inherited a massive, 25-year old code base. We have been working on improving the documentation, and have made huge improvements, but there is much still to do. There's a documentation sprint being planned for later this year at the time of our annual conference to get a bunch of people together to put together a new developer guide as well. > The X.org developers should also listen to this advice. in the case of X, this > also includes not only documenting fully how the server works and its > internals, > but also how video hardware works. http://wiki.x.org/wiki/Development -- -Alan Coopersmith- alan.coopersm...@oracle.com Oracle Solaris Platform Engineering: X Window System _______________________________________________ xorg@lists.freedesktop.org: X.Org support Archives: http://lists.freedesktop.org/archives/xorg Info: http://lists.freedesktop.org/mailman/listinfo/xorg Your subscription address: arch...@mail-archive.com
