Documentation for any software project is difficult to develop, especially when one has modest funds and/or time available, lets face it we are all coders, and we all have jobs to do, and writing software is hard enough to get done in time without adding even more work on to your plate. Fix a bug or writing documentation? Get the release out on time or documentation? Add this feature that the software really needs and users/clients/self are clamoring for or write documentation? Is not that one is trying to avoid doing documentation, but there are always higher priority things screaming for your time.
Projects can go one for ever in this state of affairs, I try to squeeze in what I can but have such little free play in my time that any extended work on documentation doesn't happen. Its not that I'm lazy, its not that other programmers are lazy, its just there isn't enough time in the day... Curiously enough, I've yet to be commissioned to write documentation, in all the years of development, clients just want training, support or new feature development.
So.. how do you break this state of affairs? Distribute the workload can help a bit, but it doesn't cut the mustard. The wiki is vehicle for allowing us to distribute the workload of documenting the various aspects of the project, and it is a useful resource, but it doesn't deliver on the nice concise package of documentation that is ideal for learning - such as a programming guide, or detail reference manual. So how do you achieve the later? GPU Gems style might be possible, but it still needs a framework to hang off, and someone to drive it, and try and have guest authors write different chapters. This style will be interesting maybe, but is likely to fall short of a good book for learning a new topic, a page turner that takes you on a journey on enlightenment. For this you need just a few authors and they have to work very cohesively, they also have to have good story telling and technical authoring skills. Such a book is now small undertaking.
Basically I'm crap at writing English. It takes me a great effort to write even small bits of text and it is full or grammatical errors and spelling mistakes. My brain was wired up badly for communication at an early age, I have to live with the consequences, and so do all that ever have to read what I write :-)
So. I'm not a great candidate. I might have the knowledge, but getting it out of me in a coherent fashion is like pulling teeth.
We do have two good candidates thankfully. Paul Martz has now gone full time consulting, and has "form" on the technological authorship side - the "OpenGL Distilled" book about as good proof as you'd want. Don Burns is also a great writer, combining knowledge and knack for the story telling side of authorship. Alas Don is just as rushed off his feet 110% as I.
Paul has been in discussion with Don and I about the possibility of a book, and there may even be some slightly indirect ways to help fund a bit of its development. However, I'd like to see such work pay properly, just as normal contracting work, this way one can concentrate on it without needing to drop it for a couple of months to help pay the bills.
Chris' suggestion of future readers punting up cash is one I have thought about as a possibility before. Could it work? Personally I'd rather see a book funded like this and published online under an open license, with hard copies later bought for hard cash. Self publishing might be enough to keep costs down that pennies put into the project would mostly go to those working hard on the book.
I also wondering if corporate sponsorship might work, with rather than a $50-$100 here or there coming in from end users, having various companies put in $1000+ would be able to make a project happens much sooner. Sponsorship has to make sense, its effectively advertising, so a page in the book on the sponsors could accompany personal lists of sponsors. Book pages also translate into web pages.
And then there is corporate donations where the sponsorship is anonymous. There are a number of big companies that are in and around the OSG community that aren't too prone to signing and dancing about using the OSG officially, but perhaps they could pony up some reasonable donations.
Another way might be to hold events that raise funding for the book effort. For instance training sessions could be done, with a modest premium added to the costs of training, and this could be into the documentation fund.
We could also contact Blue Peter and arrange a bring and buy sale.
If we can pull together enough income for the book, the work could extend to the code and the website. Ideally I'd like a whole coherent website, book and software that all key into each other and make sense individually, but become really compelling once you tie them all together.
Suggestions?
Robert.
_______________________________________________ osg-users mailing list [email protected] http://openscenegraph.net/mailman/listinfo/osg-users http://www.openscenegraph.org/
