Dirk Reiners wrote: > Hi Allen, > > Allen Bierbaum wrote: > >>> 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. > > Honestly I think the main difference between examples and demos is the > amount of test data.
That makes sense. But I would also say that demos may try to pack more capabilities into a single application and in many cases provide an interface for trying out different things. For example, the nvidia demos like nalu and vulcan are not examples. We are a long way from making something like that though so lets worry about that when we get to it. At this point I would suggest we just create a directory for "examples" and create subdirectories for each example. Put the code in there for the applications and build them as part of the common build (to make sure they don't break and get them into the nightly build). Once we get to many application examples in there and some of them are too large or too well documented, then we can start debating which ones should be demos and which ones should be tutorials. I would rather have people spend time writing examples then debating "what is an example". :) > >>> 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. > > Agreement here, so. > >> 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." > > Just showing the feature shouldn't taking a lot of code over what Marcus > and I described. For a good demo you need good data more than anything > else. What needs more work (maybe) is a demo that has a GUI to show with > and without the feature or something like that. I can help with this. If we could come up with a list of demos we want on the wiki and the data needed for then, we have some artists on staff that could create some of this data in their downtime between projects. Side-note: This is kind of like the need for a roadmap. Until someone lays out a plan that shows the direction the project is going to head and what is needed, it is difficult for people to know what needs to be contributed. >> 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. > > Can you point out the ones that you think are most typical of what you > think we need? I've went through about half of them them now, and they > don't really do more than our tutorials (i.e. set up a rather simple > scene and draw it). You may be right here. Personally I find some of them to be a little more complex and terse then the OpenSG tutorials, but they may have improved them since I looked last. >> 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. > > Hm. Unit tests are really more targeted at self-running verification of > specific situations and features resp. parts of features. Examples are > more for interactive use and show a full feature. I was just trying to think of a way to get "working" code snipets of 5-10 lines into the documentation. ie. little pieces of code that show how to use the interface of a class but not how to use it in an entire application. This type of thing may not be needed right now though. I would rather have people spend time writing examples then trying to figure out how to extract code snipets and put them in the documentation. Summary: Let's stop talking about this and just start making it happen. Dirk, tell us how you want it to be and then let's make it so. :) -Allen ------------------------------------------------------------------------- Using Tomcat but need to do more? Need to support web services, security? Get stuff done quickly with pre-integrated technology to make your job easier Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642 _______________________________________________ Opensg-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/opensg-users
