Been discussing with Craig from Amherst, Daniel from Sweden, and Kevin from Denver, ways that help requests or questions could be captured for purposes of creating better documentation. Here is one idea that is pretty simple actually. We would have to set up and agree to some rules.
The first rule. If anyone has a help request or question about some aspect of Open Media Project implementation, whether on IRC, GDO, ichat, etc., that question or request needs to be routed to one central location.
We've set up Open Atrium at intranet.channelaustin.org. We could use Open Atrium and maybe set it up as intranet.openmediaproject.org (I'm quick to say I'm not wedded to Open Atrium and if someone else has a better idea, then please say so.)
Anyway, there is one central location where Cases (as they are called in OA) will be created for each help request or question. A Case can be left unassigned or assigned (i.e. directed to a specific person)
When a Case is created a notification can be sent. This can be designated.
Somehow we'll need to figure out how to route the questions to the appropriate people. A lower level implementation question can be answered by more people than a higher level development question.
The second rule. When a help request or question has been successfully answered then the person who asked the question originally is responsible for taking the thread of conversation (if there ends up being a thread), and creating a How-to on a book page (or some other agreed upon documentation format).
If the person who asked for help or asked a question doesn't take the time to create a documentation page based on the successful answer, then they will ultimately lose privilege to access the central location where questions are being answered.
Obviously there is no way to enforce this completely and there would be instances of when people would simply answer questions without directing that person to some seemingly longer process.
But this could be one way to capture the numerous questions, and their responses, and a way to sort of force the answers to be turned into documentation by making that as a requirement for getting the question answered in the first place.
Again, we don't have to use Open Atrium. This is an example. And there may be a better work flow to adopt. I'm just trying to figure out a good way to capture the various queries and capture the responses.
Because as the Open Media Project grows, more and more people will be asking the same questions over and over again. And if we can capture those, and have them available in a well indexed manner, then people can be directed to the documentation first.
So really the process would be if someone asks for help or has a question to first consult the documentation, if the documentation doesn't exist (which is the case a lot of times), then they'd create a Case, which turns into an answer, and then adds to the growing pool of documentation.
So, if intranet.openmediaproject.org was established, anyone with more than general questions about OMP would get an account on that intranet site and be directed there.
What do people think?
Comments
I like this. So GDO would
I like this. So GDO would then be more for announcements & updates?
I wouldn't want to maintain the Open Atrium install over time -- but as long as someone else is down for that it seems like a fit. I kind of love this still: http://getsatisfaction.com/openmedia, just because it's so easy to use and seems 'friendly', and self maintaining... but it probably has its own drawbacks.
Open Media Foundation
OA install is easy
Installing OA is easy. Took not long at all. All out of the box. No configuration. There appear to be options to customize. What would maintain the install over time mean?
Installation is super easy --
Installation is super easy -- I just tried to upgrade my install a few weeks ago (I'm very interested in using it at some point to manage our tasks internally), but ran into a bunch of conflicts with modules I had upgraded since the initial install. I didn't spend more than a couple hours trying to get it resolved however, and I'm sure with the energy for OA here there's enough support to maintain it.
Open Media Foundation
Simplification
@Stefanwray, the OA install looks good, @civicpixel and getsatisfaction is even more user friendly, but I'd like to avoid adding another potential repository.
The setup of the OMP site allows for editing, I think we could just create a Questions page, and add links to the relevant new content as the Qs are answered, and revisit the screencast content type to have a searchable screencast directory.
All of us who've benefitted from previous email, IM, IRC, video chat and in-person help should be collating that knowledge to post.
While most answers are not necessarily discrete, and usually lead to further questions this should get us underway, in fact it's good that lots of new people are now implementing the OMP as the asking of Qs anew will show us what documentation is most needed.
Using OMP site.
Assuming you mean www.openmediaproject.org - well one issue with simply creating a Questions page is that it doesn't seem like there would be any way of sending (or getting) notifications when a Question had been posted. So without regularly checking that page, Questions could linger there unattended. What I really like about OA (or any other type of tracking system) is the capabilities for assignments, keeping track of the status (open, resolved, deferred, duplicate, closed), of sending and receiving notifications. A simple Question page wouldn't allow for that.
A "Third" Rule . . .
I would suggest that a "third rule" could be that a somewhat consistent "style" or "format" be adopted for the presentation of the final "How To" and "Frequently Answered Questions" pages. A person (or team of a couple people) could contribute by offering assistance in editing the "How To" pages to make them easier to follow. I would be pleased to help in this regard.
Friendly Amendment Accepted
I completely accept your friendly amendment of adding a "third rule" and welcome your offer for editorial assistance. Who are you by the way?
Hello Stefan & Everybody . .
Hello Stefan & Everybody . . . I am Kevin Jeske with Community Television of Knoxville (ctvKnox.org) and CommunityProducers.com. We have been using Facil since the beginning of time and I have been using Drupal for the last 4 or 5 years.
At CTV, we are currently installing and configuring the necessary Open Media and MERCI modules to replicate as much of the Facil functionality as we can, including the handling of inventory, project management & reservations. We are very confident about our ability to install and configure drupal modules, (including simple modification of php code when necessary), but we are NOT developers and would be the first to admit that we are not very lingual in some of the more "techy" aspects of this project. We do however, share everyone's excitement about the potential of this project and want to do everything we can to help provide a road map for others who want to install it.
Without sounding too much like an OA fanboy...
...I do think Open Atrium provides a good system to organize documentation, as well as organize/manage information from multiple sources. Their community site also provides some good examples and guidelines on how to manage community maintained documentation.
To see how this might look, we've already set up a group on our OA based Drupal Kata site. If it's decided this type of platform/system may facilitate community involvement, I'd be interested in looking for ways to integrate into OMP and maintain.
I like Stefan's ideas about how to get people to contribute to documentation, but I'd lean towards looking at what incentives we could provide rather than any sort of strict requirements or punitive measures.
Gus Austin
Carrot is better than the Stick
Of course you're right. A Carrot is better than the Stick. What Carrot do you have in mind?
I like the layout and navigation on https://community.openatrium.com/documentation-en
I'm looking at this site http://drupalkata.com/openmediaproject/notebook and seeing that you started a similar looking page.
It'd be good if the documentation is the most public facing information and that it is accessible to anyone without a username and password, but that in order to post questions or submit help requests registration is required.
Would there be an easy way to make it so that a registered user who submits a help request and then converts the final answer into draft documentation for the editors could receive points (thinking of your incentives) and that by earning more points for converting more queries into documentation that registered user gets something in return -- like maybe their queries get pushed to the top of the queue?
Registered users start with a bank of 10 points, and if they consistently convert query-answers to documentation, their point bank balance goes up. If they consistently do not convert query-answers to documentation, their balance goes down, and all their subsequent queries since to the bottom of the list (i guess we could use Views to sort the list of queries/questions by point bank balance as opposed to by most recent).
If registered users sink below a certain point bank balance they get put into "the box" where they will be completely ignored and the only way to get out of "the box" is to perform some useful task.
Or is this over-complicating things and making this into too much more work than it already is?
Public facing and registation required
It's Drupal so we'd be able to set up the site anyway we want. Before thinking of what sort of tools would help provide incentives we'd need to decide if integrating OA into the workflow would be a good idea. I'm not sure how we'd reach a consensus on that....
Gus Austin
No objections.
I'm not hearing any objections. Perhaps a bit of a reservation from synchlayer. And support from others.
Who would we need consensus from?
Another OA fanboy
I like the Open Atrium approach too. I think the current handbook is very difficult to navigate, difficult to subscribe to updates and there is no task tracking system connected to it. With Open Atrium it would be easy for people with login to ask a question and it will then be assigned to whomever is best suited to answer it. Or rather, we could assign ourselves questions that we think we could answer either by writing or by a screencast.
I don't really see a reason as to why keep two differerent systems to this, it's a bit too much work to move finished answers to another system. Why not simply use Open Atrium for the entire documentation and task tracking process? Then anyone can see if a question has been asked by others, but only those who have been granted access can ask questions or edit the notebook/documentation (public access, moderated registration).
I like GetSatisfaction too, but that is more of a system for asking questions and discussing, not as much for the documentation itself. The Open Atrium case tracker could handle such questions pretty well in our case, I think, since there's still a limited user base.
My 2 cents,
Daniel W
How about using the issue
How about using the issue queue for the modules? At least for documentation/questions specific to the modules. I check the queue's daily. For me the issue queue is the simplest way to locate and track things. Every few weeks I'll pile through the queue and hammer out the bugs. So even if open atrium is used if the bugs/feature requests aren't in the issue queue then it's easy to miss them.
I think the difficulty of
I think the difficulty of using the modules' issue queues is that it's quite often difficult to know what module a question belongs to. And many questions are general in that they don't particularly relate to an OM module, but maybe Views, CCK or something even more general like themes.
I would also prefer that any
I would also prefer that any module-specific issues/documentation that get posted into OA on openmediaproject.org get cross posted to the specific modules when relevant. It seems like OA would be a 'safe' place to start those conversations for those less comfortable with the module issue queues, and then once the basics are ironed out of whether it is just need for more documentation, or an actual issue or feature request it get copied over to the appropriate issue queue.
Open Media Foundation
I wouldn't recommend moving off d.o. and g.d.o.
Definitely agree that we keep using d.o. for feature requests, bugs, etc. for all the modules and the install profile itself. Also think that this space on Drupal groups should continue to be the place for general discussions about the project. Open Atrium again could be good tool to manage/organize documentation. We could even pull in feeds from the d.o. issue queues, relevant Drupal groups, and anywhere else it would make sense. Another benefit of improving the openmediaproject.org site(s) is it may raise awareness and increase involvement from those outside of the drupal world.
Gus Austin
do gdo omp irc
So we're looking at something like this as a structure (not too dissimilar to what exists now). Correct?
drupal.org -- OMP/MERCI module bug reports and feature requests but NOT support requests (support requests routed to OMP.org)
groups.drupal.org -- announcements, updates, non-technical discussion, entry point for new people (support requests routed to OMP.org)
irc -- developer interaction for work on bugs and feature requests (support requests routed to OMP.org)
openmediaproject.org -- support requests, help, questions, documentation NOT bug reports and feature requests
For this, openmediaproject.org gets a complete overhaul with Open Atrium laid as the base code. Existing handbook content is converted into OA notebook hierarchies (and marked for what needs to be updated, because I sense there's a bit of that). Other extraneous, old, no longer used, irrelevant content is zipped up into a nice little archive folder and stashed away nicely somewhere.
I am hearing that gusaus, KAP10, possibly westis, maybe civicpixel, and me would want to be part of the core team that starts this translation. Anyone else?
Sound like a plan?
I nominate gusaus as the team leader since he appears to have the most knowledge about and enthusiasm for OA and can help with structuring the migration. I'll help with prodding things along and bugging people and whatever initial editing work needs doing and whatever else rolls along.
Ready. Set. Go.
High level view
It seems like we're getting a bit beyond the scope of the discussion. If there's consensus that OA would be a better system to organize/manage documentation we need to figure out how best to implement. I'm not sure what the overall goals of the openmediaproject.org site were/are... but we should figure that out before deciding to move the entire site to OA.
@stefanwray - Possibly you could create a wiki 'Open Media Project website' and paste in some of what you posted above?
Gus Austin
High level response
I'm worried that if we get too bogged down in discussion that nothing will get done. We've been saying that documentation is a problem for a long time.
For arguments sake, let's pretend that we have a consensus that OA would be a better system to organize/manage documentation.
Given that assumption, what do you think would be the best way to implement it?
The overall goal of the openmediaproject.org site was to serve as a landing site for the project where new people could go to get more information on the project - both a high level description of the tools as found in the section on features, as well as detailed documentation regarding how to install, configure, and use. The goals for the site have been to house information that would be useful for developers, implementers, and staff users of the project's tools.
I don't think that much of that has changed or needs to change. It just needs to be done in a way that is better and more systematic.
Sandbox for an example
I went ahead and set up a sandbox -
http://openmediacommunity.dev2.webenabled.net/dashboard
While the site is currently inspired by (https://community.openatrium.com/) it should provide a starting point regarding how this could work.
Any initial thoughts?
Gus Austin
dev.openmediaproject.org
@civicpixel cloned a copy of openmediaproject.org for me to sort through the content for purposes of preparing it for a migration to OA. there were 304 content records. now there are 205. deleted what is obviously not important now and removed some content types
@gusaus i'm curious about importing content from the existing handbooks to OA notebooks
Use WebEnabled for development?
We've been using WebEnabled for Drupal Kata demo sites and sandboxes. The (free, hosted) platform provides some great tools for this type of collaborative development and subsequent deployment. More info here...
http://www.webenabled.com/how-it-works
I could easily set this up for further evaluation if I was provided the files/db of the current site or clone.
Any thoughts?
Gus Austin
In addition to or instead of OA?
Is this a suggestion for in addition to or instead of OA?
It's a hosted development platform
Currently hosting the sandbox referenced above.
Gus Austin
Are there some problems with
Are there some problems with the existing hosting environment? If we are looking for a more collaborative development environment with revision control for the OMP site, I would suggest we check it into github. Although, it seems unnecessary to the current discussion.
Open Media Foundation
A forum on openmediaproject.org?
Is this too oversimplified or unfeasible, but what about setting up a forums section on openmediaproject.org? Or a wiki page here at gdo?
Once an issue has been resolved - create a book page on openmediaproject.org using the guidelines.
I have to mention one other
I have to mention one other documentation resource I love, http://www.flossmanuals.net -- this is the tool that CiviCRM used to create their book: http://en.flossmanuals.net/civicrm, which has been very helpful for many of our clients.
It falls prey to the same 'outside of the openmediaproject.org' site argument, but provides a lot more functionality in regards to producing a full manual.
Open Media Foundation
My 2¢
I've held off on getting involved in this discussion hoping it would end up going in a new direction this time around. Looks like we're heading for another trip around the same circles.
While we could refactor all of the documentation (again), since the documentation is never going to be finished before modules change at this point in the project, I don't see a lot of value in that. Open Media just isn't as mature/stable as CiviCRM or OA so it doesn't make sense to copy their model. I'm not saying the current documentation is great... or even good, but reworking all of it again is going to take hundreds of hours I don't have and I don't think anyone else has either.
Personally, I'd rather start seeing more immediate payback from the people I've already invested time in. I've helped many of you understand how features and functionality work with both Open Media modules as well as Drupal in general. It's time to start passing that knowledge on. IMLHO, the Project will see more bang for it's buck it if everyone involved created a few short screencasts like what Craig did for the PBCore module...
http://openmediaproject.blip.tv/file/3957770/
The screencasts don't have to be long or even 100% accurate. In Craig's PBCore screencast he mentions the relationship between Timeslot Themes and genres, but doesn't explain how that works. That's fine! I will follow that up with a short screencast about the new structure of om_show that has the checkbox in the configuration that enables the javascript written for BAVC that makes the show metadata a multistep process when using a hierarchical gene list.
Other short screencasts I think would be helpful that I know one or more people in this group could create...
Without an incremental approach, we're always stuck in this catch 22. I keep hearing that other people will contribute to the documentation once their implementations are finished and the modules stop changing. The problem is the people writing code are never going to get the modules to that 'finished' state if we have to answer the same questions over and over again, but people that know the answer to some of the questions don't want to share that info until there is a new structure for documentation.
It's also worth noting that hunmonk and dww have been hired by the Drupal Association to improve the project management functionality on Drupal.org as part of the push to finish the redesign. The redesign should take some of UI elements people like from OA and implement them on Drupal.org. That should make it easier for non-developers to use the platform the Drupal Association funds and maintains to manage the Project vs. investing the limited time and resources this group has trying to do maintain our own version of that.
You can see where the redesign effort is at...
http://redesign.drupal.org/project/modules?filters=drupal_core%3A87&solr...
http://redesign.drupal.org/project/om_airing
As well as where it's headed...
https://infrastructure.drupal.org/drupal.org-style-guide/prototype/modul...
https://infrastructure.drupal.org/drupal.org-style-guide/prototype/modul...
In a great example of eating their own dog food, the team working on the redesign is using Drupal.org to manage the project...
http://drupal.org/project/redesign
Since the vision for what the om_support module would do has really been dropped, I'm going to suggest we follow the redesign team's lead and go back to using that module's issue queue for reporting problems where the module responsible is unclear. Anyone with a CVS account can move issues from one module to another and assign them to other users with CVS accounts.
When we talked about this before, Lane from BNN was the only person who requested a CVS account.
Before we invest time reinventing the wheel, can we at least try the tools on Drupal.org?
Using the Drupal.org issue queues offer integration with CVS commits that save developers time. Adding another system is not going to remove Drupal.org. Non-public access users will continue to post errors, feature requests, and contributions on Drupal.org. Instead of helping to free up development time, this approach requires the developers to monitor 2 systems.
If Stefan, Craig, and Gus had CVS accounts and access to om_support project, they would get an email every time a new issue was added to om_support and could move that issue to om_show, om_project, etc as well as assign it to the someone else if they couldn't answer it. As the redesign moves forward and Drupal moves from CVS to Git, managing projects on Drupal.org will only get easier. My understanding is features like the up/down voting you already see on GDO will find their way into the issue queue allowing the community to help prioritize as well as subscribe to issues and feature request.
To get a CVS account, simply make a request in the om_support issue queue like Lane's request then complete this form http://drupal.org/cvs-account with a link to that issue.
I think there is a need for general, non-developer discussions. I'm not sure that OA is the right platform to build http://community.openmediaproject.org/ on, but I'll leave that to the people who want to lead that effort.
Again, can we at least try doing this the Drupal way before going the OA route? I feel like the people pushing for OA haven't even used Drupal.org's features. If you try it and it just does not work or the benefits don't outweigh the UI differences, I'll concede to using OA, but let's at least expose everyone with an opinion about OA to the alternatives so we're making educated decisions.