0.6 Documentation Plan

We have two goals for technical documentation we want to write in the 0.6 timeframe:

1. Enable a python programmer to be able to develop a flickr-like parcel without someone from OSAF in the room.
2. Document technical decisions made in 0.6, leave a paper trail.

This page gives an overview of the documentation we expect to write for 0.6 to support the above goals. All 0.6 documentation tasks will be tracked as bugs in bugzilla.

• Table of Documentation Bugs

Non goals for 0.6 (given the large investment, too early to tackle this):

• clear and complete enough documentation that someone could download chandler and contribute major parcels and bug fixes without ever talking to someone at osaf
• equivalent of an oreilly book for chandler

0.6 Specs and Guidelines

0.6 specs support the second goal listed above. You can think of the audience for these specs as OSAF developers on another team who don't know the details of what you are working on. The audience will likely end up being wider than that, as this documentation will be useful for people digging into the project later, including people who write more polished docs down the road.

• Technical specs created for this release (ZeroPointSixPlanning) should be updated for by the end of the release. They can be frozen at that point, the scope of those specs is to describe 0.6. The goal of these specs is to leave a paper trail of technical decisions.
  • Collection spec update Bug#4191
  • Recurrence spec update Bug#4190
  • Sidebar/appbar writeup Bug#4026
  • Detail view/attribute editor writeup Bug#2965
  • Update i18n spec Bug#3741
  • Schema api implementation and relationship to repository Bug#4186

• Guidelines docs are one of the results of i18n work and api cleanup
  • Busy developers' guide to i18n, guidelines Bug#3590
  • What is an API guidelines document (post substance of pje's email to wiki)

Tutorials

Tutorials support the first goal listed above.

• Zaobao tutorial will be replaced with an updated "feeds" tutorial to reflect the current state of the parcel. This tutorial will be an "advanced" tutorial. Bug#4027
• We want a short document that lists the available repository types, which we found we wanted at the sprints. Bug#4028
• A new tutorial on how to write a new sharing conduit. Example: would allow a developer to add RDF sharing conduit. Bug#4033

We cut these docs -- after first drafts we realized they overlapped with other docs and generated docs:

• We want a similar short document with a list of blocks and events. The first draft is available hereBug#4030
• We'll write a variant of the introductory paper we used at pycon, updated to use current APIs. Bug#4031

Architecture and Reference Documents

Architecture and reference documents are useful for supporting both goals. Architecture/overview documents should be readable by someone new to the project. Reference documents do not need to give background on other topics, as this will be covered by other docs. Tutorials will be the main support for newbies wanting to jump into parcel writing, the docs listed below act as background material in support of that as well as useful reference and big picture documentation for those of us steeped in the project.

• Epydoc is desired for any api that shows up in a tutorial.

• Overall architecture document Bug#4032
• Schema API doc for use by parcel developer Bug#4186
• Document about startup: /parcels/osaf/startup.txt
• CPIA overview Bug#3226
• CPIA script Bug#4214