One of the most exciting parts of the Open Media Project is the potential that the collaboration between 7 locations has to move this project forward more quickly than if just one location drives it. So far, most of the Open Media System specific code is being developed in Denver. We are hoping to see this slowly change as we deploy the modules at each location and everyone becomes more familiar with the modules, CCK, Views, Drupal's CVS repository, patches, issue queues, etc.
While transitioning we expect a truly distributed development community to evolve over the next 6 months, we are hoping to see contributions from our partners in this project more quickly in the Open Media System's documentation. Writing good documentation is as important as development... and often just as/more time consuming. It is also something developers don't always do very well for a number of reasons.
One idea we've been testing is hosting a community editable version of the documentation at om.civicpixel.com that everyone with permissions can edit and distributing the structure of book pages that simply displays/pulls the content of the "master" page into placeholder page using PHP. Each location would have the option of adding additional documentation be for or after the main documentation... or even replace the documentation completely.
http://om.civicpixel.com/handbooks/user-guides/adding-member-your-project
Then the page on DOM's site would simply pull the content into this page..
http://www.denveropenmedia.org/handbooks/user-guides/adding-member-your-...
Using some simple php like this...
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "http://om.civicpixel.com/handbooks/user-guides/adding-member-your-project");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$page = curl_exec($ch);
$page = strstr($page, '<!--START OM DOC-->');
//$page = strstr($page, '<div id="book-navigation', true); // Only with PHP 5.3.0
$page_parts = explode('<div id="book-navigation', $page);
$page = $page_parts[0];
print $page;
curl_close($ch);
?>The partner locations would have the same page pulling the same content...
http://davismedia.org/handbooks/user-guides/adding-member-your-project (doesn't exist yet)
As features are added and interfaces improved, the documentation would continue to get updated across all 7 locations as anyone with time made the update. Obviously there are issues with keeping the version of modules in sync with the documentation, but this was the easiest way we could come up with to collaborate on documenting the system.
Anyone know of a better way to do this?
Comments
No one suggested anything
No one suggested anything better, so I added some logic to deal with images to the curl script I posted earlier and rolled it into the Open Media Support module. Partners and alternates can download that from http://om.civicpixel.com/code.
With that module installed, handbook pages on each site are just a placeholder page with PHP enabled that looks like this...
<?phpom_localize_documentation('http://om.civicpixel.com/handbooks/user-guides/making-reservation-step-step');
?>
http://www.urbanapublictelevision.org/handbooks/user-guides/making-reser...
http://www.denveropenmedia.org/handbooks/user-guides/making-reservation-...
I started writing some documentation about writing documentation, but haven't gotten very far with that. It would be really helpful if someone would step up and suggest some standards for writing, reviewing, editing the Open Media System's documentation.
documentation standards template
Kreynen wrote:
Is there a template or typical format for documentation that can be used as a model to apply to the Open Media System's documentation?
I don't have a template, but
I don't have a template, but I'd use any template we can agree on.
My wife does a lot of process documentation for eCollege, but they do everything in Word so I'm not sure that will translate, but we could definitely require some custom .css to format the handbook pages and add those styles to TinyMCE's styles menu.
Once thing I've been doing is scaling down all the screenshots so users are less likely to get confused between images of forms and the actual forms.
Not design, but writing style
Rather than the design or layout of documentation, I'm more curious now about a format and structure for documentation in terms of the writing style. When we say we want to document this project, what exactly does that mean? How deep do we go? What level of detail on procedures and processes? Is our goal to establish documentation so that anyone can replicate this at any public access tv station or community media center? Are we talking about detailed technical documentation of Drupal modules and code only? Or also higher level product type documentation? So I'm wondering about examples or models or templates for this.
Updating Export DXML
I took a first stab at updating the Export DXML module. I posted a D6 version of the module to the Export DXML issue queue. That version installs in D6, but needs more work to make the export with.
Anyone interested in helping with the Open Media Project who doesn't have time to get involved in the larger workflow, this would be a great place to pitch in.