On Dec 14, 2007 7:59 PM, Zachary Hilbun <[EMAIL PROTECTED]> wrote: > To me an API is only as good as it's documentation.
I'd suggest that the OSG is proof that point of view is a perhaps just a little flawed. Good documentation but a poor API and implementation don't make for successful end user applications. However, with a good API and implementation you do have a least have chance of making something useful. I'm not suggesting not having good documentation is not a great thing to have, obviously great documentation and great API and implementation is all what a perfect project would be composed of. >From my experience with the OSG project, its the software that solves the problems at the end of the day, and the majority of contributors to the OSG and clients who pay for parts of the OSG to be developed have a problem to solve so they write the code or fund the work to do it. One can say write the documentation first then the software, it might work for you, but so far for the hundreds of contributors to the OSG this hasn't been the case, the gifts that are given tend to be source code. Thankfully there has been exceptions, the QSG was a funded documentation effort, and there have been efforts like the ref manual by Paul Martz and Bob Kuehne, but alas the revenue from books does match the level of effort put in so it is a case of labour of love. Work on the tutorials, wiki and examples are also gifts to the community. However, this work is still in minority - few people have time to spend on activities that don't directly result in getting their project deadlines met, and alas few companies have tens of thousands of dollars to put towards serious documentation efforts. I do like the idea of small white papers on different topics, small chunks of documentation are much easier to squeeze in a free day here or there, than spending many months on a major book. Coherency with such works is more difficult though, but still wouldn't detract from their usefulness. Personally I'd love to see enough funding to employ a fulltime technical writer, failing this perhaps part time. Would companies be prepared to help fund documentation effort? Such as by sponsoring or just straight donation? The amounts we'd need to find would be ten of thousands of dollars to be able to do do any significant chunks of work. Thoughts? Robert. _______________________________________________ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
