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

[John Vidar Larring]

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.