Dirk Reiners wrote: > [snip] > >>OK, this one is easy to figure out. Look at your users today. Look >>at the users of other scene graphs. I believe most of them have at >>least an engineering degree or are in the process of getting one. >>Thus they should have a background in linear algebra and as they >>are interested in graphics they most likely know OpenGL. I think >>that's the target. Just a minority has a PhD I believe. >> >> > >But how far does the OpenGL go? If I tell them the parameters for the >BlendChunk are for glBlendFunc, is that enough, or do you think we need >to list all possible alternatives? > > I think referring to glBlendFunc is fine. It would be really great if it was a link that went to some online docs. :)
> [snip] > >On Fri, 2006-08-25 at 08:54 -0500, Allen Bierbaum wrote: > > >>I may be missing something here, but aren't we turning down help and >>contributions here. I totally agree with Marcus, if someone is willing >>to help, give them access and just review their submissions. This will >>get them involved and remove work load from the developers. This is >>exactly the type of thing we should be doing to build community. Let >>people start small by contributing documentation and then grown into it >>from there. >> >>As far as using patchs to review documentation instead, I tend to think >>it is much easier to review a contribution by clicking on a link in an >>e-mail that goes to a webpage with diffs highlights and formatted then >>it is to: get a patch, go apply the patch (correctly), run a diff in >>text mode to check the changes, and then commit the changes. >> >> > >I'm sorry, but I have to agree with Gerrit on this one. Giving SVN write >access to just everybody sounds like a dangerous proposition. I don't >know anybody who does it > >Given that documentation would be mainly addition, I'm not worried about >understanding where things go. Give me 3 lines of context and reviewing >documentation become very easy. > > I am not suggesting you give SVN write access to everyone. What I am suggesting is that if a user or part-time developer comes to you and says "I would like to help out with documentation, here is a sample", then we let them have svn access to help out. Initially it will probably be somewhat probationary but still, if someone wants to help it seems to me like we should let them. One of the other reasons I think this is a good idea is that, at least from my experience, I am much more likely to contribute documentation and other "small" changes to a project if I have commit access. Making a patch and submitting it may sound very simple (and it is), but it does take more time and effort then a simple "svn commit". > > >>If people want to become involved, why turn them away? Are we worried >>we would have to many commits in a day to review? I can't wait to have >>that problem. :) >> >> > >Nobody's turning anybody away, I would like all the contributions I can >get. But turning over the key to your house to the guy that offers to >mow your lawn is a little too brave. > > Not if he has mowed the lawn before and I have cameras all over the house watching him and if he does anything bad I can roll back the state of my house. :) > > >>It is not too much to assume as long as you document which area of the >>spec to look. For example you could just say that any gl enum that is >>valid for this param of such and such method would work here. That way >>people don't have to try to figure out how the field gets mapped to the >>opengl call behind the scenes. This is especially hard in sections of >>the code that use advanced capabilities of OpenGL and the user is not an >>advanced OpenGL user. >> >>I guess that may be part of the problem. I would describe the current >>OpenSG expected user as: >> - Expert in OpenGL >> - Expert in C++ >> - Working to advanced knowledge of math for graphics >> - Able to read and understand low-level graphics code >> >>This seems like a very high bar to just use a scene graph. >> >> > >True. I wouldn't that's the expected user, but that is kinda who the >docs are written for right now. > > > >>I think we should target people who have: >>- medium experience with C++ >> (they can use it but they may not be able to write a template functor) >>- Basic knowledge of OpenGL >> (they know what it is and have written basic code, but don't know >>advanced method and don't read the spec) >>- Working knowledge of mathematics for 3D graphics (know matrices, >>vectors, may not know Quaternions, probably don't know slerp) >> >>Also key is, they are using a scene graph so it is likely that they may >>not want to know about the low-level details of the graphics library >>(OpenGL). They are people that want to load their data and write code >>that uses it. >> >> > >Sounds reasonable. > > > >>Trac has a plugin that allows you to download a version of any wiki page >>in PDF by just clicking on a link at the bottom of the page (just like >>the existing "Plain Text" link). So I think even if people want a >>printed version we can satisfy that by just making a trac page that >>pulls all the sections of the guide into a single page. >> >> > >How do you do that? Can you include other pages into a united page? > > I think so. > > >>Important classes, use groups. >> >> > >We're doing that already. Not excessively, but we're doing it. > > > >>Examples, look into the doxygen example support. May just want to >>document the examples source code using doxygen and then include those >>examples into the documentation so they can link into the reference guide. >> >> > >Link into the ref guide or links to them from the ref guide? > > Links from the reference API to a possibly included page that has the source of the example. I think doxygen supports this. > > >>Run faster: Run it less often, buy a faster machine and harddrive. :) >> >> > >I got a dual Dual-Core Opteron running on a raided filesystem. If you >need more than that to build the docs we're in trouble. ;) > > If only doxygen were multi-threaded. :) >[snip] > > >On Fri, 2006-08-25 at 18:12 +0200, Carsten Neumann wrote: > > >>from personal experience I can tell how GNU Classpath handles this - >>for a GNU project they are pretty liberal AFAIK. >> >>- new contributors send patches marked [RFC] (request for comment) to >>the patches mailing list (should we have one ??). >> >> > >Hm. I don't think we need a mailing list. Trac combines all of that as >tickets, and those can be commented on by everybody. I think that should >be ok. > > Related to this, I think we should setup a mailing list for notifications of all ticket adds and changes. That would be much easier then visiting the tickets everyday. :) >>- if accepted a project member with write access commits on behalf of >>the contributer. >>- after a couple of accepted patches write after approval access is >>granted, meaning that a RFC mail is still required, but if the patch >>is approved the contributer handles the commit on her own. >>- senior members still send all changes as patches to the list, but as >>an FYI (for your information) and commit immediatly. >> >> > >Sounds good to me. A little too complicated, IMHO. > > >Summary: > >- Everything should be documented everywhere (units etc.). >- Target audience has a little OpenGL experience, but not too much. Same >for C++. Think late undergrad student. >- There is a way to turn Trac pages into PDF. We need to find a way to >merge multiple pages onto one, and then we should be able to put the >Starter Guide/ Related Pages/ Tutorial in Trac. > > See WikiInclude: http://trac.edgewall.org/wiki/MacroBazaar See PageToPdfPlugin: http://trac-hacks.org/wiki/PageToPdfPlugin -Allen >- Rather than giving everybody SVN write access, we'll use Tickets for >docs patches. > > >But all of this means that we will have to rewrite or at least >significantly extend a large part of the existing docs. We will need >some help with that to get it done in any kind of reasonable >timeframe... > > > Dirk > > > > > > >------------------------------------------------------------------------- >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 > > > ------------------------------------------------------------------------- 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
