wiki:Dev/Documentation

Introduction

Documentation and examples are crucial to get things going. Especially since OpenSG, at the moment, has many advanced features but little documentation on them.

General

  • 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.

Contents

High-level docs

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)

API

  • 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.

Solutions:

  • 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

Building documentation

  • Doxygen is quite slow on large projects, and OpenSG is indeed large.
  • Building API docs takes a _long_ time.

Proposal:

  • 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).
Last modified 8 years ago Last modified on 01/17/10 01:11:44