Re: [osg-users] Community Documentation Initiative [Was: Too much support!!!!!]
Hi Roland, Ok, I'll try to merge the two during the weekend. - John 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 Roland -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] 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@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@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org -- 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@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] Community Documentation Initiative [Was: Too much support!!!!!]
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: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] 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 h
Re: [osg-users] Community Documentation Initiative [Was: Too much support!!!!!]
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: [EMAIL PROTECTED] > [mailto:[EMAIL PROTECTED] 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@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@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] Community Documentation Initiative [Was: Too much support!!!!!]
Hi all, please see below... Robert Osfield wrote: Hi John, On Tue, Jun 3, 2008 at 9:21 AM, John Vidar Larring <[EMAIL PROTECTED]> wrote: 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 This is a good start. One could link the actual example code available in svn to the example as well so one can browse the source. One could also introduce an extra column for an screenshot and a column for the main classes used in the example, in addition to the wordy explanation. * Column for thumbnails/screenshot added (Please set image size to 200x150). * Added links to SVN source code. Add text in front of source link. I have a threading bug to chase up right now so I'll get my head down once again... Yes, please do;) Best regards, John -- This message has been scanned for viruses and dangerous content by MailScanner, and is believed to be clean. ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] Community Documentation Initiative [Was: Too much support!!!!!]
Hi John, On Tue, Jun 3, 2008 at 9:21 AM, John Vidar Larring <[EMAIL PROTECTED]> wrote: > 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 This is a good start. One could link the actual example code available in svn to the example as well so one can browse the source. One could also introduce an extra column for an screenshot and a column for the main classes used in the example, in addition to the wordy explanation. I have a threading bug to chase up right now so I'll get my head down once again... Robert. ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
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@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] Community Documentation Initiative [Was: Too much support!!!!!]
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... 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 -- __ Jean-Sebastien Guay[EMAIL PROTECTED] http://www.cm-labs.com/ http://whitestar02.webhop.org/ ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
[osg-users] Community Documentation Initiative [Was: Too much support!!!!!]
Hi all, I have tried to resist to reply to the "Too much support" thread for over a week now, but now there's just something I'd like to share on a related topic. 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: 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. 2) Summary and detailed documentation of the tools that come with VPB. 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. Simple example: Current documentation of osg::observer_ptr: /** Smart pointer for observed objects, that automatically set pointers to them to null when they deleted. */ ...could be changed to: /** Weak pointer for observed objects, that automatically set pointers to them to null when they deleted. * @see http://en.wikipedia.org/wiki/Weak_reference */ Documentation submissions could be marked with "doc-only" or similar topic tags. These suggestions have arisen from my own personal needs for documentation, so I am sure that other things can be done as well. I, for one, intend to add more documentation as I start to figure things out, and I hope other will do the same, both newbies and experts alike. IMHO I believe that an improved documentation can also help reduce the general support load on Robert, or at least facilitate newbies in asking more intelligible questions. After subscribing to osg-users for a few weeks, I know that there are lots of users out there that know an awful lot about undocumented OSG tools/examples/features/classes. I hope I have managed to convince at least some of you to participate in a "community documentation initiative". Best regards, John -- This message has been scanned for viruses and dangerous content by MailScanner, and is believed to be clean. ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org