Marcus Lindblom wrote: >Allen Bierbaum wrote: > > >>So you want to pull the examples inline into the class docs? Or could >>we just do something like Qt where we refer to the full applications. >>Doxygen would even let use have the code for that full application >>example be syntax highlighted with links back to the documentation of >>the classes and methods being used. >> >>I guess I would rather see full examples that show how to fully use the >>system, then see trivial examples that still sound like tutorials to me. >> >> >I think Dirk's writing on the wiki sums up my opinion pretty good as >well, and they don't really agree with your point here. We need to >settle on concepts and names. What we have is: > >Examples: 5-10 lines of code, preferrably inline in the class dox. >Perhaps referenced to from a larger 'tutorial document'? > > To me this is not much of an example. It is just a code snippet. It doesn't really show the capabilities IMHO. I would prefer to just link from the classes to more extensive examples. See my comments on the wiki.
>Tutorials: small but complete executables that larger concepts (like >your "full examples" above), with small data. Usually less than a meg. >Source could be referenced to from class dox. > > I think of tutorials as showing a single concept for the purposes of teaching. >Demos: large applications, potentially tens of megabytes of data. >Referring from class dox to the source of these is not necessary, IMHO. >I..e mentioning in FBOViewport class that 'SurfaceScatterRhubarbPieDemo' >extensively uses it is sufficient. Linking to the actual source is not, >as there should be an example and a preferrably a small tutorial as well. > > Agreed. >I think the divisions into the three concepts are pretty sound. Do you >think we need something not covered here? Do you have good reasons to >change the names we will use for these concepts? Do you have better >names? For sure, a tutorial could be used to 'demonstrate' a concept or >so. It would just not be branded as a 'demo' (hrm... ;). > > The big thing I see missing is a consensus on examples and the fallout from that. If examples end up being small pieces of code then we have lost 2 major things that we need IMHO. 1. Marketing demonstrations of new features. I know I have harped on this a lot, but it is vitally important. OpenSG has no marketing, zero, nada. We have tons of features and new ones all the time but nothing to demonstrate them. I want something in the standard build that shows these capabilities so when someone adds feature X, the very next day we can go to opengl.org and announce "OpenSG adds feature X, download the nightly from here and run Xexample." 2. Examples for people to base real applications and that show real usage. snipets and tutorials only show a very simple way of using most code. In a "real" application it normally has to handle more issues and deal with more cases. We need applications like this for people to base their applications and look to for "examples" of using the code. Take a look at the examples directory in the OpenSceneGraph dist. It is exactly the type of thing I think we need for examples. They have 81 examples of simple applications showing off and using the capabilities of OSG. This is what OpenSG needs. If we still need little 5-10 line code snipets, that is fine, but I suggest making them part of something besides examples. Really something like that may be part of the unit tests. >I'm all for settling on different namings, if there are better >alternatives. Half of design is defining concepts and defining names for >said concepts, the rest is just trying not to confuse the two. ;-) > > Agreed. Let's hash it out on the mailing list and then update the wiki with the definitions we agree upon. -Allen >Cheers, >/Marcus > >------------------------------------------------------------------------- >Take Surveys. Earn Cash. Influence the Future of IT >Join SourceForge.net's Techsay panel and you'll get the chance to share your >opinions on IT & business topics through brief surveys -- and earn cash >http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV >_______________________________________________ >Opensg-users mailing list >[email protected] >https://lists.sourceforge.net/lists/listinfo/opensg-users > > > ------------------------------------------------------------------------- Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT & business topics through brief surveys -- and earn cash http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV _______________________________________________ Opensg-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/opensg-users
