Hi all,
next round. ;) Again, summary at the end.
On Thu, 2006-08-24 at 10:54 +0200, Antonio Bleile wrote:
>
> Ah, interesting ;)
> I think you should mention it every time. At least looking at Qt
> they do mention it every time. I don't think it's too much an effort
> to write this standard sentence into the doc of a method.
OK.
> I agree with other posters that we should involve users/contributer
> to do this kind of doc. From their painful experience they should
> know best about all the pitfalls and problems one might encounter.
I would think so, too.
> Where did he end up anyway? Can't we "reactivate" him?
He's working on his PhD at the University of Koblenz
(https://www.uni-koblenz.de/FB4/People/Person/abert), but I don't think
I can find funding for a second round.
> ok, but at least he can google for it, I think that's Gabriel's
> point.
The first hit on both Wikipedia, doesn't really make a difference.
> > Given that float comparisons without epsilon don't make sense, I would
> > expect it to use osgEps. Again, convention.
>
> Write it down. Users are generally stupid and mistrustful. ;)
Hearing that from a user is not a good sign. ;)
> 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?
> If the documentation is well done they should not include source
> code at all. I usually do so for qt: If things are not clear I go
> and grep in the source code. As this happens just once a month
> it's more than ok.
That sounds like a rule of thumb: if you need to look into the source
only once a month, the documentation is good.
> I think you can sacrify the printed version. Users can print topics
> from the wiki if they want to read them somewhere off the computer
> (toilet, train, airplane, etc ;)
That's one vote.
> As detailed as needed ;) Sorry.
;)
> Again, again and again: I don't expect that the whole code gets
> documented, but at least the part that is most likely to be used
> by a "user". That leads to a question: Would it be somehow possible
> to separate the two things? I mean a layered model, there's the
> OpenSG core underneath and a small layer on top of it which is
> the actual API:
>
> +-----+
> | API |
> +-----+
> +---------+
> | Core |
> +---------+
>
> ??? Can you somehow hide the internals (at least parts)?
Yes you can, by putting ifdefs are the code that are only used by
doxygen. We do have some of that (user vs. dev doc), but it's not used
very much. I don't know how much we can really cut, though, as there is
not a lot of non-user-visible stuff in OpenSG.
> Could we collect some data from users which methods/classes
> they actually use? Some code parser which extracts all the
> OpenSG related methods.... That could be really useful info
> for you. But I don't know how to do it ;(
That sounds interesting. But it's hard to do for C++, as polymorphism
prevents you from just looking at the source. Not sure which tools are
out there that could help with this. Any one?
On Thu, 2006-08-24 at 11:14 +0000, [EMAIL PROTECTED] wrote:
> Currently I use it only as .pdf file because I can then easily search
> for key words etc. But during the first learning phase I think it was
> very helpful to have a complete document which I could print. I think
> nobody really reads a complete book direct at the monitor. But I do
> not think that is has to be always updated to the latest information.
Well, it has to stay correct, so I don't think we can afford updating it
rarely. If we put the Related Pages on Trac, putting them all together
into a PDF is going to be difficult. Any ideas on this one? Is there
something like a PDF output for Trac, that we could use to create pages
to compose? Alternatively we might be able to convert the pages on Trac
back to Doxygen, as long as some simple rules are followed.
I would like more input on how important this is before I spend a lot of
time trying to solve it.
On Thu, 2006-08-24 at 14:15 +0200, Haykel BEN JEMIA wrote:
>
> One possible solution would be to add a page to the new OpenSG site
> where users can add such information and perhaps organize it in themes
> (Basics, Scene Graph Management, Clustering, Advanced Rendering,
> etc.).
>
> The documents don't need to be very detailed, even a list of actions
> to achieve something would be enough. In a later step, someone(s)
> could review these documents and correct/extend them and perhaps add
> parts/all of them to the official doumentation.
I think the FAQ and HDI are the places for that. We might want to add
some things to the docs, too, if they make sense, but for submitting
things the Wiki is probably the simplest way.
On Fri, 2006-08-25 at 08:07 -0500, Allen Bierbaum wrote:
>
> I think this is a bit of a cop out. It makes it easier to justify not
> writing documentation, but that doesn't make it true.
Partially true, admitted.
> How hard is it really to document a member variable when it is added or
> document a new method when it is created. The developer is already
> adding it, so they know what it does. It only takes about 30 seconds at
> the most to write a one or two sentence description of the thing.
Nope, it's definitely more. You need to copy the documentation template,
and documenting everything is going to take more time than that. Not
sure how much more, but from the times I tried, documenting is a serious
addition and not just the little addon you talk about.
> Documenting method behavior is a little more difficult, but once again
> when a developer is writing a piece of code they are already doing this
> in their head. They are thinking, what will this code do, what are the
> inputs and how will it work. Once again I would say that it doesn't
> take more then a minute to write this down for most methods.
Not from my experience.
> For most new classes that I write and try to fully document I would say
> that if the class takes 2-3 hours to write and test, then documenting it
> probably takes about 10 minutes of that time at the most.
Good for you! You must write faster than me, then.
I'm not trying to cop out here, I'm just relaying my experience.
On Fri, 2006-08-25 at 08:54 -0500, Allen Bierbaum wrote:
>
> No, but if they click on the return type link (BoundingVolume) in the
> reference guide it should go to a page about that class that does
> explain in detail what a bounding volume is and what the conventions are
> for them in OpenSG.
Just for reference, there is no BoundingVolume class, and all the
volumes can be used for more than BundingVolumes, so we're not talking
class docs, but concept docs here (i.e. what is a scenegraph and what
happens inside one).
> 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.
> 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.
> 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?
> 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?
> 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. ;)
On Fri, 2006-08-25 at 10:53 -0500, Allen Bierbaum wrote:
>
> That is what nightly builds are for. If somebody breaks the build then
> they are in trouble. If they do it multiple times then revoke their
> commit rights unless/until they prove themselves again.
I'm more worried about inadvertent (or malicious) changes that don't
break the build but add semantic bugs.
> It would be interesting. It is a much larger project though so I am
> sure there is more overhead then what we may want. A smaller project
> like apache httpd or python would probably be a better match.
Python seems to have an informal process about getting adopted
(emphatically called the School of Hard Knocks:
http://mail.python.org/pipermail/python-dev/2002-September/028725.html).
They have 66 people with commit access and 7 people who are
administrators on SF (who can add devs), which for a project the size of
python (including all the libs is has) doesn't seem like an awful lot,
certainly not just everybody.
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.
> - 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.
- 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
