r14 - 04 Feb 2006 - 14:45:35 - LisaDusseaultYou are here: OSAF >  Journal Web  >  CommunityHome > WikiImprovement > OsafWikiContentReorg20050718
This project was more or less completed in 2005 so I'm archiving it to the journal now. --Lisa

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 Journal Documentation

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

Part 1: planning Target: Jun 25
Publish this proposal to the Wiki Done
Post notices to dev and blog Done
Find Twiki templates and get change access Done
Identify Web site pages with links to Wiki pages that will change Done
Figure out how to update templates Done
Write a script to change name of a Wiki and fix in all the wiki pages Done
Test script on local copy of wikis Done

Part 2: major changeover Target: June 30
Rename 'Chandler' to Projects and run script Done
Create new Projects page based on LisaDusseault20050613 Done
Move Cosmo pages to Projects wiki Done
Edit Web site pages to fix Wiki links Pieter volunteered
Edit 'oops' template to note Wiki name change Done
Make Journal green (it's prettier) by editing WebPreferences Done
Edit twiki.dev.tmpl to remove link to Jungle Done
Create a a WebTopicEditTemplate? asking people not to add pages in the Jungle Lisa
See if we can make Projects show up first in search results Lisa

Step 3: before Chandler 0.6 release:

Put Glossary in Documentation. Done
Clear out old Glossary page template. Lisa
Create a new Documentation. Done
Bring in the dozen or so actual Documentation pages we already have (that are today in the Chandler area or on the web site). Lisa
Update OsafWikiWebStructure. Done

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?:

Comments, notes

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

Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r14 < r13 < r12 < r11 < r10 | More topic actions
Open Source Applications Foundation
Except where otherwise noted, this site and its content are licensed by OSAF under an Creative Commons License, Attribution Only 3.0.
See list of page contributors for attributions.