wiki:docGuide
Last modified 5 years ago Last modified on 12/29/08 17:41:10

Documentation Recommendation

To achieve a somewhat consistent documentation, some thumb rules are listed as recommendations. This is not a policy, if someone feels otherwise let him write his part as it happens. But nobody should feel upset either if others try to harmonize the docs to common shape so that its consumer would find it more consistent to read and it would have some logic as a whole.

URL Components

  • url style: dirs/under/dirs instead of wiki names. see title index how this appear.
  • url parts: camelCase, first letter low, new words start with capital letter.
  • url case: as much in lower case as possible
  • No need to mention OpenSync in url anymore, it's in domain name already.

URL Hierarchy

  • Version specific material is organized under version structure and eventually can stay there as is, when new versions are released.
  • When trunk is mature enough for branching, a copy of it's docs should be made under release docs and let the trunk to be broken for next big changes.
  • Features that appear in trunk, but most likely live in upcoming versions too, but do not exist in earlier versions are first put under /trunk/features/longWaitedFature and when next release is done, moved into that particular version tree.
  • Generic material should have as short urls as possible when they are not release specific. For examplelike /wiki/status page is.
                             PROPOSAL FOR URL STRUCTURE

/devel/                    (developer docs)
/meetings/
/bugManagement
/hackers                   (list of people and their specialities)
/status
/faq                       (contains pointers to release specific pages)
/join                      (instructions to join our community)
/plugins                   (for general non-version specific information)
/plugins/syncml            (intro, non-version specific material, pointers to docs)
/plugins/gpe
/plugins/opie
/releases/0.2x/notes
/releases/0.2x/docs
/releases/0.4x/
/releases/0.4x/features
/releases/0.4x/features/capabilities
/releases/0.4x/features/merger
/releases/0.4x/faq
/releases/0.5x
/releases/0.5x/features
/trunk
/trunk/faq
/trunk/features             (once release is done, feature is moved under release where it appears)
/trunk/features/mixedTypeSync
/trunk/features/oneWaySync
/trunk/features/apiPerl
/trunk/features/apacheModule
/trunk/installation
/trunk
/peers
/peers/nokia
/peers/nokia/s60v3
/peers/nokia/e71 (if there really is something device specific)
/peers/opie
/peers/scheduleWorld
/peers/se
/peers/sw/w9xx (or is there a symbian/os release for se?)
/peers/samsung
/peers/samsung/sghd600
.
.
.

Device Compatibility Pages

Not recommended to create such pages anymore for following reasons:

  • the amount of phones/pdas is vast.
  • single device can have a lot of different firmwares.
  • conclusion: number of possible device, firmware and opensync combinations is vast.
  • active hackers only have access to subset of devices.
  • occasional hackers don't have time to familarice themselves with documentation structure and all different aspects of opensync.
  • as end result, wiki process cannot provide consistent, even adequate quality documentation for some particular combination.

CREATING DEVICE COMPATIBILITY LISTS IS NOT RECOMMENDED

Instead there is already a split structure to describe each piece separately:

  • peer - which can be hardware device or service
  • plugins - that provide a feature that may match with peer
  • documentation? - how to configure particular OpenSync version based on information learned from peers and plugins page.