Proposal to reorganize OSAF's wiki content

This proposal is to take a series of steps to organize our Wiki content into three major wikis that each characterize a style of document, rather than a topic. I think all the work we write about at OSAF can fit into one of these three wikis according to how polished it is and for what audience:

Projects wiki

Audience: Mostly OSAF people and regular code/bug/doc contributors.

Polish/relevance: Medium; we expect these pages to be either reasonably maintained or have information with a certain amount of static relevance.

Top areas: Chandler projects, Cosmo, Scooby.

What it contains:

• Information that is useful for people with some project context.
• Information about past releases, the latest release, current work and future plans.
• Project pages like the ones we have today.
• Links to project specs (which remain in SVN).
• Links to Documentation pages -- e.g. in SharingProject, link to HowToShareCalendars^? in case somebody finds their way to a project page when they really wanted documentation.
• Info about smaller projects like Zanshin, Projects.PyLucene, M2Crypto, or our contributions to outside projects like Twisted.
• Who is in which team or working on what thing.
• Design documents, proposals -- except when the creator feels more comfortable tossing them into Journal
• Development processes and practices.
• Checkin, binding, bug-finding and other guides for people who contribute to any of the projects we decide to host.
• Most of the information that is currently in the existing Chandler wiki area, plus new similar information being created for Cosmo and Scooby.
• See also LisaDusseault20050613 for the set of links that one might find on the front page of Projects.

Journal wiki

Audience: Typically this is "one's self" or a select audience. This information is broadcast less widely than project information.

Polish/relevance: Low. This can be wild ideas, half-baked notes or stuff that's almost immediately out-of-date -- like my "current active stuff" for Jun 16 2005.

Top areas: Staff notes, meeting notes, proposals... however we don't worry about keeping areas organized.

What it contains: All the material currently in the Journal plus, in the long run, Jungle material.

Documentation wiki

Audience: Mostly non-OSAF people who use or are interested in our projects, including CSG and WAC and similar.

Polish/relevance: As high or higher than Projects area, sometimes high polish. More carefully maintained and relevant.

Top areas: Chandler end-user docs, Cosmo administrator's guide, Parcel Developer's guide, Tourist guide.

What it contains:

• Documentation that contains the context one would need to go from zero to achieving some focused task other than directly contributing to one of our projects. Tutorials. Help pages. White papers.
• Presentations that we gave to outside audiences that may still be useful.
• Product and release overviews intended for public consumption. Mostly related to the very latest release and cleaned up with each release.
• Planning and vision material suitable for audiences like WAC and CSG.
• Probably auto-generated API documentation.
• See also <http://wiki.osafoundation.org/bin/view/Journal/LisaDusseault20050614> for an outline of links in each proposed area.

FAQ #1: why not organize by topic? E.g. Chandler, Cosmo, Scooby? Because there are too many topics that cross boundaries like "CosmoChandlerInterop" and "ChandlerScoobyGuiCommonalities", as well as topics that aren't strictly part of a major topic, like "CalConnectPlanning" or "BuildSystems".

FAQ #2: Why is "developer documentation" now split across areas, with parcel developer documentation in Documentation, and other stuff in Projects? Because contributors to our projects are very different from developers who want to independently write their own parcel.

• For contributors, detailed parcel tutorials may not be relevant but much other stuff is and we can't predict very closely what will be relevant.
• For parcel developers, our dev/QA processes, specs, builds, tasks, detailed status and ideas aren't relevant.
• For parcel developers, we must produce documentation that is up-to-date with the last released version, reasonably polished and provide all the needed context.
• For parcel developers, less is more. They don't want the firehose (or if they do they click on Projects)
• We expect contributors to necessarily have to slog through more of our random project management stuff although we'll try to help them too.

FAQ #3: What happens to the existing areas and content? Note: some of these areas are hidden but you can see them when you try to move a page...

• Chandler --> Projects
• Journal --> Journal
• Glossary --> part of Documentation
• Jungle --> eventually folded into Journal, but temporarily may be hidden and only show up in searches.
• Users (actually called Main) --> Stays around for technical reasons, but doesn't need to be a major area because it only contains user pages of limited interest. we'll put a link somewhere else on the template, not at the top with Projects | Documentation | Journal.
• Trash (which is already a hidden area) --> Stays a hidden area and used to save obsolete pages.
• Know (already a hidden area) --> Gets cleaned up someday?
• Sandbox (already a hidden area) --> Stays hidden and continues to be used for Wiki testing.

Transition Plan

Step 3: before Chandler 0.6 release:

Then during Chandler 0.6 release we can update parcel developer and tourist info in Documentation to be relevant to that release. New CSG documentation and presentations can be dropped in here as soon as they're ready.

Step 4: Date Jungle pages according to when they were created (e.g. turn "WikiLikePIM" wiki word into "WikiLikePIM20030130") and move them into the Journal. Remove the PageInfoForms^? or at least clean them up (status is not used, comments-welcome is not used, too many types). Consider other cleanup like the "Know" area and "Plugins".

Stuff to do to remove or reduce PageInfoForms^?:

• AboutPageType^?
• PageListByPageType

Comments, notes

Interesting post on what kinds of project management can be done with Wikis