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

[Paul Melis]

Smeenk, R.J.M. (Roland) wrote:
>  
> Note that there already exist an example page with screenshots and some descriptions here
>
> http://www.openscenegraph.org/projects/osg/wiki/Support/UserGuides/Examples 
>   
Hmm, so there now are two pages.
One at Support/UserGuides/Examples that has screenshots for most 
examples, details a bit how to set the correct env. variables (handy for 
a first time user checking OSG out) and has few descriptions.
The other one is Support/Examples. It has links to the actual code of 
the examples, which is really nice to have, but it doesn't offer much 
compared to the first one. I suggest the links to the code get 
merged/copied over to the first page and we change the Examples links in 
the menu to point to that page. Unfortunately, that seems a lot of work. 
I'm willing to help with this...

Paul

>
> 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
>
> _______________________________________________
> osg-users mailing list
> osg-users at lists.openscenegraph.org
> http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
>
>