Hi Nick, Documentation is certainly and issue, not just for code but for how the project is run, how to use the various resources etc. There is actually a huge amount of resources out there, but it very distributed and not coherent enough.
To address the issues of documentation I believe we need a team responsible for it - a documentation working group that looks at the project from the view of how to communicate how it works better and tackling various tasks in improving things. We need people to take on this responsibility and help work on improving things for the long term. This is very much a long term solution, you can't just flick a switch an have all the documentation we want to help us, it'll have to be written bit by bit and over time it'll help the project more widely such as enabling more of the community to become active contributors more quickly. Given the time frames involved it documentation efforts won't be able to relieve load on myself in time for me scaling my unpaid work on the project back down again. Robert. On Tue, Feb 23, 2010 at 2:00 AM, Nick Schultz <[email protected]>wrote: > Perhaps there should be an enforcement of better commenting standards on > submitted code. This might reduce the load of questions being asked by the > community as they can understand the code better and increase the amount of > users who can answer them effectively. Obviously the tricky part is how > much better is "better" and what is "good enough?" That can be another > discussion. > > Also, if the user/developer base is more informed of the codebase, you can > also have more people who can process submissions > > Another question arises, how do we better comment/document the current code > base we have now? Well that can be up to the community, you can let it be > known that OSG is currently looking to improve its documentation and users > who find themselves stepping through code to understand various sections, to > take the time (time they are already spending walking through and tracing > code) and add comments where needed (preferably the parts that confused > them). I know for myself, when I was trying to learn some parts of the > code, thought that some parts could have been documented better. The OSG > quickstart guide was very helpful in my understanding of OSG. > > These ideas may be logical, but I'm not sure on the practicality of it all. > This is my first open source project and biggest project that I have worked > with to date, so I may be out of my league and for that I apologize. :P > > Good luck with your investigation :) > > Nick > > ------------------ > Read this topic online here: > http://forum.openscenegraph.org/viewtopic.php?p=24659#24659 > > > > > > _______________________________________________ > osg-users mailing list > [email protected] > http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org >
_______________________________________________ osg-users mailing list [email protected] http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
