Hi Tim, On Dec 15, 2007 9:20 AM, Tim Moore <[EMAIL PROTECTED]> wrote: > > * We could embark on the much-promised and long-awaited "Programming > > Guide". Again, this is a big job and only seems worthwhile if we focus our > > efforts on stable features. > I'd love to see this and I know it would be a big job. I think you could > enlist the > community's help with this and still make as much money with the book at the > end of the > day.
In the past we've tried to encourage community documentation, the original pmwiki and then the move to Tracs were both motivated by the hope that they would help such a community effort. Community documentation efforts have so far tended to be small little pockets of activity that soon die down as developers move on to go there "day job" done - basically everybody is really busy almost all the time. So far real documentation like the Ref Guides, the Quick Start Guide and the Tutorials has happened when you we've had a small set of developers that have a primary goal of doing tutorials/documentation. It takes a lot of time and focus to be able to do it, general community support can help, but I doubt will be a primary resource of manpower. I think we need to get past the thought that if we just create the right conditions for the community to contribute documentation then it'll just happen for anything beyond small stints of couple hours here and there. If we want good documentation then we need to focus on how to create the right conditions to enable individuals to commit the majority of their time for substantive blocks of time. > > > > * We could spend time writing short whitepapers on various OSG topics, > > similar to Don's useful document on reference-counted memory. We could sell > > these as PDFs for a couple dollars a pop or something, depending on scope. > > Possible topics would include rendering order with RenderBins, deriving your > > own Nodes, Drawables, or StateAttributes, platform-specific topics, > > resolving build and installation issues, using the Geometry class, > > performance issues, etc etc, the list is essentially endless. > > > This route would be quite unfortunate. Like everyone else on this list I'd > love to see documentation on these topics, but as someone who has shared what > he has > learned the hard way on some of these very topics, I think it would be a > shame if > the authoritative advanced documentation was in a per-pay product. Having > this kind > of documentation freely available shows off to the world the advanced uses of > OSG, > inspires the community, encourages others to give back, etc. > > I absolutely respect your need to make a living, and the above subjects > should certainly > be covered in any book on OSG. I might suggest that you start shells for > these subjects > on Wiki pages, either the official OSG one or your own where you make it > clear that you > retain a "compilation" copyright. Add what you know to the pages, then later > use them > as base material for the book. I don't know the economics of your book sales, > but I > can only believe that high-quality free documentation won't hurt the sales of > a good > book on OSG. Um... you want great documentation for free on the promise that you'll buy other great documentation... Experience form the QSG is that if there is free and the is paid for in a hard copy form, free wins almost all the time. Even the paid documentation is unlikely to pay for itself in terms of time put in, so the idea that one can afford the time to write free documentation as well and still have a viable hourly pay rate is simply not realistic. Book sales on niche technical books very rarely exceed the costs of production, we'd need to sell ten's of thousands of books to start seeing any reasonable return. So please guys, can be get a dose of realism here. Good documentation is hard and costly. The community haven't be able to magically write lots of great documentation, free books won't ever pay there way and just eat in sales of bought books, and bought books will always be in the minority and don't pay for themselves. This is the reality as it stands right now. The reality is also that the best documentation we have is subsidised, the QSG by the terrain deformation project, the tutorials from NPS and the ref guides personally by Paul Martz and Bob Kuehne. In part the ref guides are loss leaders for Paul's and Bob's OSG Training, by mostly they are benevolent, a gift of their time and effort and as such should be cherished. We can't just live off the good will of others, people have to pay mortgages, put bread on the table. We need to be realistic about how we create and sustain the conditions that members of the OSG community can help write documentation. Members of the community have to help subsidise the effort of writing documentation via funding others time, or by getting their organizations to put aside blocks of their time towards so they can help with the effort. To me funding of documentation needs to come from individual contributions and from companies/universities donating money, the later is what I'd see as being the most viable route. In terms of organizations putting time aside time for their staff to help with documentation, I feel that universities that teach computer graphics students have a direct need for documentation/tutorials so would a natural candidate for helping put time of their staff into developing resources that can be used internally but also be openly published. So please, any volunteers for time or cash? Robert. _______________________________________________ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
