[osg-users] Community Documentation Initiative [Was: Too much support!!!!!]

[Smeenk, R.J.M. (Roland)]

Note that there already exist an example page with screenshots and some descriptions here

http://www.openscenegraph.org/projects/osg/wiki/Support/UserGuides/Examples 


Roland


> -----Original Message-----
> From: osg-users-bounces at lists.openscenegraph.org 
> [mailto:osg-users-bounces at lists.openscenegraph.org] On Behalf 
> Of John Vidar Larring
> Sent: dinsdag 3 juni 2008 10:22
> To: OpenSceneGraph Users
> Subject: Re: [osg-users] Community Documentation Initiative 
> [Was: Too much support!!!!!]
> 
> Hi all,
> 
> I have created a new page on the wiki that list all the 
> example programs that comes with OSG in table form. In the 
> TOC is listed under "Documentation | Examples". If you (excl. 
> Robert at this point) are familiar with or have authored any 
> of the example programs, then please go to the page below and 
> add you input. Newbies like me will be ever so grateful.
> 
> http://www.openscenegraph.org/projects/osg/wiki/Support/Examples
> 
> Best regards,
> John
> 
> Jean-Sébastien Guay wrote:
> > Hello John,
> > 
> >> I'm a total newbe to OSG and as a newbe I hunger for info. 
> Here's a 
> >> few things that I am really missing, and I think most of 
> these things 
> >> can be done by the community rather than Robert:
> > 
> > All three of your ideas are really good and pretty easy to do. Some
> > comments:
> > 
> >> 1) There are lots of excellent example programs provided with OSG. 
> >> However, I sometimes find it hard to find the example I 
> need to study 
> >> to solve my newbe questions. What I'd really like to see 
> on the wiki 
> >> is a list of all the example programs with ditto summary of what 
> >> features they demonstrate and techniques used.
> > 
> > Excellent idea. There have been requests before to document the 
> > examples themselves (code comments), but this is a big job 
> and hard to 
> > coordinate. However, a wiki page which lists all the examples ('ls 
> > OpenSceneGraph/examples', copy-paste) could then be filled 
> by people 
> > gradually...
> 
> See;)
> http://www.openscenegraph.org/projects/osg/wiki/Support/Examples
> 
> > In general, I think the wiki could use a "chief editor". 
> Some info is 
> > well categorized, but other info is a bit scattered. But 
> before this 
> > happens, I think we need to be able to create accounts on 
> the wiki so 
> > that people are accountable for their changes.
> > 
> >> 2) Summary and detailed documentation of the tools that 
> come with VPB.
> > 
> > Check the archives, Robert has stated that once the major 
> work he is 
> > doing on these was done, he would start documenting them. They are 
> > currently moving targets, so any "formal" documentation 
> might be out 
> > of date really quickly. But if anyone has the time, they 
> can start and 
> > at least write the parts for the tools that look like 
> they're stable.
> > 
> >> 3) For all OSG classes, I'd love to see more high-level class 
> >> information (e.g. purpose, etc.). For certain classes that 
> implements 
> >> special programming techniques, it would be wonderful if the 
> >> documentation included a link to external resources explaining the 
> >> technique in general.
> > 
> > Yes, that would be great. In general, the doxygen comments are very 
> > low-level implementation details (or what a method does, instead of 
> > why it does it). So the kinds of info you're suggesting 
> would help a lot.
> > 
> >> Documentation submissions could be marked with "doc-only" 
> or similar 
> >> topic tags.
> > 
> > Another good idea. In general, I think tagging messages would allow 
> > Robert to ignore some categories of threads where the subject alone 
> > doesn't say enough about it.
> > 
> >> I hope I have managed to convince at least some of you to 
> participate 
> >> in a "community documentation initiative".
> > 
> > Personally, I have always agreed that it was needed. The 
> hard part is 
> > coordinating this work and getting it all done, when most users are 
> > busy working on their actual jobs. But I think it's a case where if 
> > someone steps up and agrees to take charge (I can't in this case, 
> > sorry) then the community could make small individual steps 
> that when 
> > taken as a whole, would count for a lot.
> > 
> > I hope this becomes a reality soon. I'll certainly participate.
> > 
> > Thanks,
> > 
> > J-S
> 
> 
> --
> Best regards,
> John
> WeatherOne
> 
> 
> -- 
> This message has been scanned for viruses and
> dangerous content by MailScanner, and is
> believed to be clean.
> 
> _______________________________________________
> osg-users mailing list
> osg-users at lists.openscenegraph.org
> http://lists.openscenegraph.org/listinfo.cgi/osg-users-opensce
> negraph.org
> 
This e-mail and its contents are subject to the DISCLAIMER at http://www.tno.nl/disclaimer/email.html