Documentation and examples are crucial to get things going. Especially since OpenSG, at the moment, has many advanced features but little documentation on them.
- The user should only have to download one package, the full OpenSG, where there should be locally contained docs explaining everything
- Website should link to precompiled doc for all major releases and HEAD/trunk.
- Documentation needs to have one good Front Page (tm)!
- Link to 'tutorials', 'examples', 'user guide', opensg-web, etc.
- Provide a snapshot of trac-wiki? (might be hard to resolve links properly, unless all doc is snapshotted from server)
- Recruit a "documentation team" to work on a sprint to document as much as possible.
There needs to be a developer guide that explains the design and inner workings of the current core. This should *not* be in extreme detail since we need to make sure it stays up to date. It may just be references to doxygen generated documentation that gives a mental framwork for how things hook together. (ie. how all the internals connect and work together)
- Too many classes have no documentation and then the user has no idea what they are for.
- Users currently have to reverse-engineer the API's and usage rules.
- Users need not see implementation details.
- All classes should have some description of what they do and what they are for. #59.
- Split doxygen doc into two:
- User (does not change OpenSG useful as quick reference)
- Developer (works within OpenSG, or user who needs more info).
- Autogenerate docs on server.
- Develop documentation standard. #62
- Make documentation work a natural part of coding:
- Convince developers to document the code as they write it and keep the docs up to date.
- Write some test to see if classes/functions are untested. Post report to mail-list (similar to boost).
- Define the "important classes", start documenting them and move on from there.
Investigate setting up a 'doc-police-bot' that reports documentation status? /ML
- Doxygen is quite slow on large projects, and OpenSG is indeed large.
- Building API docs takes a _long_ time.
- Split different parts into different doxygen runs. Cross-reference.
- Build documentation in dailybuild (minor doc changes in trunk need not be tested by user then).