At dinner tonight Add1sun and I chewed over the question:
Why does Drupal's contrib maintenance model largely work, and handbook maintenance does not work?
While Drupal's contrib area is certainly not perfect, it has active maintenance on many projects, and a clear sense of ownership, and rules that go with that ownership. Everybody can contribute in the issue queue, and everybody can comment in the issue queue. But the maintainers are responsible for the their project.
Interestingly enough, our Handbook does not have those attributes. Everybody can edit most articles, but there's no notification, no discussion of the changes, and most of all, no real ownership or rules that go with the ownership. Many people will edit a page to fix a small inaccuracy, but few will take over and maintain a section of the handbook. And of course nobody gets the glory when it goes right, or the blame when it goes bad.
So here's a solution that takes no additional technology at all: Create contrib projects for the various parts of the handbook. Have maintainers that care for them and take responsibility for them. Have an issue queue related to them. You could even have hierarchical projects without any additional technology. Just have the project page link to the parent and the children. (Or, of course, project nodes could be book nodes.)
This technique allows a clear line of responsibility for a section of the handbook, but still lets everybody contribute just as they do now (but more so, with a narrowed issue queue. [Yes, I know, documentation already has an issue queue... but it's too big and too indistinct.]).
So what would this do?
- Allow delegating "maintainership" of a section of the handbook to one or more maintainers
- Provide an issue queue for discussing that section
- Adopt the existing (largely successful) contrib module of maintainership, with its ways of declaring a project abandoned, etc.
Essentially, we could imitate the existing successful contrib model. I think it might work.
The one technical detail we might need to address is that a maintainer needs a feed of changes to their section of the handbook. If we can get a feed, we can get email notifications if required.
Thoughts?
Comments
If it's feasible, I'm all for it!
And I volunteer to maintain the Accessibility section of the handbook.
It occurs to me that as we talk about responsibility for sections, we also raise the issue of "ownership" of content. For example, who "owns" the section on controlling color in themes — the theming maintainer, or the accessibility (because of color contrast) maintainer?
But that issue will always exist in one form or another, and by identifying individuals with primary responsibility for each section, we would make it easier to know who to work with to figure out how much of this topic goes here, how much goes there, and how we connect the two.
Great idea!
Why does Drupal's contrib
Why does Drupal's contrib maintenance model largely work, and handbook maintenance does not work?
Because the module development process is written by developers, for developers, with feedback and contributions from developers influencing changes and the documentation process is written by developers for documentation writers with feedback and contributions from developers influencing changes.
Just like developers improve Drupal with each release for designers because we listen to designers, developers can improve Drupal as a solution for documentation writers if we listen to what they want improved.
The approach kvantomme promoted at DrupalCon of building an install profile for project documentation makes much more sense to me... and has the added advantage of incorporating feedback from users who are actually writing documentation for a living. Image a common install profile used for http://documentation.openatrium.com, http://documentation.drupalgardens.com/, http://documentation.openpublishapp.com/, http://documentation.openmediaproject.com, http://documentation.civicrm.org, etc., etc. If these groups collaborated on a documentation solution that worked well for the people writing their documentation, what would that look like? Would it require a git account? Not likely.
Just because we have a contrib module hammer doesn't make it the right solution for every problem.
On the fence
Hmm, this is an interesting idea (especially because I would really love a good way to further divvy up and delegate handbook work...) but at first glance I'm on the fence as to whether it's the "right" solution. Though atm I don't have something better to propose. ;) Will definitely ponder some more, and watch for other ideas/discussion here... and post again when I have some useful ideas to contribute!
Would be interested in hearing more opinions on what would help others to adopt some handbook sections to maintain...
Agreed
This makes well some points knocking about in my head for a while.
It seems there will be a little code needed to integrate Project module for book trees? The RSS feed per section (tree) is a great idea independently and maybe can be worked on first, then integrated with Project module.
If we let people create sections we'd want a good process for merging sections. If we don't let people create sections we'll want a good taxonomy and a way for splitting sections :-)
benjamin, agaric
make good documentation somebody's professional interest
somehow I posted this twice O_°
--
Check out more of my writing on our blog and my Twitter account.
make good documentation somebody's professional interest
This is definitely an interesting idea, however the contrib model largely works, largely, but if you look around you'll see plenty of abandoned modules also. It's true that even Wikipedia has lot's of abandoned corners and that their ownership model is not perfect (but who's is?).
I know that there are plenty of people that contribute code out of altruism, but the dirty little secret why contrib works is working so well is because people have commercial interests in being the maintainer of a module, as an indirect lead generation tool for freelance or other development work. Right now the documentation in Drupal has no real direct commercial application, except maybe as a lead generator for trainings.
So as kreynen says, just as with designers we need to reach out of our developer pond and get the professional documentation writers on board, without them, ownership would just be an extra hurdle for people to contribute. In a contrib project with a lazy maintainer the ownership is just a deterrent of improvements.
The best way to get the documentation writers on the Drupal ship is to adopt their latest shiny tool, and that is DITA.
That is why I think it makes loads of sense to move the Drupal documentation system onto DITA: it not only gives us the latest best practice tool in documentation writing, it will make Drupal the primary open source tool for collaborative DITA documentation writing and will infuse our community with new talent who write documentation for a living.
Than we can still experiment with stronger ownership, to see if it is a better model.
--
Check out more of my writing on our blog and my Twitter account.
DITA is great, but pie in the sky
The problem with all conversations about changing the technical underpinnings of docs (DITA) is that we actually have no idea how we would do that in terms of resources or plan. So it's pie in the sky. There is no path to it currently.
Experimenting with the ownership model, as proposed here, requires no development. It's a social-only change. It costs nothing and depends on nothing. And the outcome of a "failed" experiment? We have exactly what we've always had. So this is also a no-risk experiment, as far as I can tell.
-Randy
@rfay Is there a way I can
@rfay Is there a way I can interpret that so I wouldn't be insulted? I really want to believe you're not saying if you aren't included in every conversation, the rest of us have 'no idea' how to make something like this happen.
The first 10 minutes of Kristof's DrupalCon presentation, my blood was boiling listening to him talk about distributed documentation. I was thinking this is support.openatrium.com/community.openatrium.com and github all over again. Not only have we seen issue tracking and source control fork, now we're going to fork documentation too?!?
But when Kristof brought the presentation back to treating documentation distros like a localization client, I realized this would have worked for the Open Media Project and resulted in much better documentation on D.O. I had just spent 2 years trying to do everything for that project on D.O. We were able to bend the CVS policies to get non-developers access to the Project module's issue tracking and use project to manage our project. We helped fund profile packaging to streamline our development workflow. But couldn't make D.O. work for documentation. Instead like every other install profile, we developed our documentation on our own. We have never ported or mirrored the Open Media Handbooks back to D.O. for number of reasons.
Not that the OMP handbooks are perfect, but it was our first attempt at developing a system of shared/distributed documentation. As a result, it's where the Read documentation link is directed from project pages like MERCI. MERCI is now used by a more universities than TV stations. While it would make sense to move that handbook, but none of the people maintaining the MERCI documentation want to maintain two copies of that documentation. This is also true for Creative Commons and PBCore. There is documentation for implementing those modules in an Open Media configuration, but after scratching their itch the person writing to documentation moved on.
DITA supports resuse of documentation in multiple hierarchies.
If you agree that install profiles for specific use cases are going to play an increasingly larger role in Drupal's future, we need to look at documentation solutions that meets the needs of the groups developing install profiles. Allowing more control over maintaining content was one reason we hosted our documentation on http://www.openmediaproject.org/handbooks, but issues like versioning was another. You can read about my 30 minute solution to add version 2.x specific documentation with CSS.
DITA supports versioning.
Another important reason to continue the DITA conversation is that documentation writers support DITA. DrupalCon was the first time I had heard of DITA, but after looking into it I found a community of documentation writers looking for open source solutions. Heck, http://dita.xml.org/ is actually running Drupal! So that's step one... find the people in the DITA community interested in building better DITA support in Drupal.
For me, by far the most important reason for me to develop a better system for documentation is a personal one. My wife is an instructional designer who's nice enough to come to many Drupal conferences and camps. Her attempts to use Drupal have often ended in arguments. Me telling her to RTFM and her telling me to LTWAFM (learn to write a * manual). While she and her team use already Drupal to document their products and process, they use a configuration very different from the way D.O. is configured. I can't imagine that her team is the only example of Drupal being used for documentation at an enterprise level.
I've been talking with my wife's team about moving to DITA. The next step for them is a module that adds support to the WYSIWYG module for the DITA Storm editor. While not GPL, DITA Storm is the best option in the short term and building on WYSIWYG makes swapping out the editor for a GPL alternative a non-issue. The next step is to update XML Contentor develop something new to serve that purpose. Once those steps are complete, they'd be able to move to DITA based documentation. At that point some of the 'pie in the sky' projects Kristof has described become reality.
The idea of at some point in the future using Graph Mind to select and organize pages of existing documentation for a custom manual that can be displayed online or imported into InDesign for printing is exciting for people who write documentation. Probably as exciting as moving from CVS to git for someone who spends most of their time in that environment.
While implementing more maintainership to documentation and DITA are not mutually exclusive, discounting DITA as 'pie in the sky' is not helpful. I know the CVS migration was stalled several times by statements like that.
Whoa, no offense intended!
Wow, there's no way that I'm trying to offend anyone. I'm so sorry you were offended.
Here's what I'm trying to say: We don't organizationally know how to move forward with any technical solutions. We talk about them, but there is nobody with the year or more of energy required to make it happen. If that somebody is you, or you know some answer to this dilemma, then I'm wrong. But I don't think we have the resources or know where to get the resources to:
If I'm wrong, and you see a practical way and a likely way to do this, then let's do it.
I was proposing a social-only experiment. No technology, no deployment, just an experiment with ownership. This doesn't replace or otherwise alter anything we might do with DITA. It just experiments with the ownership strategy to see if we can get real people acting like owners of the parts of the docs that are theirs.
The reality is I don't think this proposal has anything to do with the entire DITA (or other redesign) initiative. It has to do with experimenting with community ownership of documentation and should be considered a completely separate thing.
Please let me continue to back away from the hole I dug :-)
I feel obliged to continue to apologize.
I should not have even have mentioned DITA in the same breath with this proposal. They really have nothing to do with each other.
What I was trying to say is: Let's not wait until we have a technical solution or an infrastructure improvement to try a social experiment.
What I was NOT trying to say: Let's not do DITA.
Am I off the hook yet?
@rfay Because I know you to
@rfay Because I know you to be a truly positive person, you were never really in a hole :)
I agree that there's no reason to wait for a DITA supporting install profile to add maintainership to the documentation structure, but we should keep in mind the potential for an increasing amount of non-core documentation to come from install profile projects and DITA when making changes on D.O.
As Dries would say, I see no reason http://documentation.apple.com, http://documentation.adobe.com/, and http://documentation.microsoft.com/ can't be running on Drupal.
progress report
I know that I've been talking about a lot of fancy new things, but I don't think this doesn't have to be pie in the sky for too long. After I posted the UI prototype demo movie (this Sunday), I've been contacted by 4 people from the DITA community. An open source tool for DITA writing has been the thing a lot of people have been waiting for, and a lot of them are already using Drupal...
Yesterday I had 2 meetings with people from the DITA community:
-One with Don Day, the chairman of the OASIS DITA Technical Committee. He is working on an open source framework for DITA editing, based of CKeditor some part of which might be usable for our purpose.
-One with Yves Barbion, who owns a company that is writing technical documentation in DITA for a living. He has been reaching out to our community for about 2 years now, to get DITA moving. He also sent me a script that transforms mindmaps (graphmind uses the .mm format from freemind) to ditamaps. I haven't tried it out yet and it might be for an older version, but it means we are not starting from 0 making ditamaps with graphmind. Once I have one of my colleagues available (which should in the coming weeks) we'll try to put together a demo for that.
So between Kevin, me and my colleagues from inside the Drupal community and the enthusiasm from the DITA community, I think we can make this move forward pretty fast. That of course doesn't make the required effort for migrating to DITA any smaller :(
--
Check out more of my writing on our blog and my Twitter account.
Mapping Freemind .mm to ditamap
Today I also posted a blogpost with a very feasible (2 weeks development or so) plan for a Drupal site that can output ditamaps based on Drupal dita topic nodes. You can see it at http://www.pronovix.com/blog/mapping-freemind-mm-ditamap
--
Check out more of my writing on our blog and my Twitter account.
Agreed, Randy
I have to agree - they are pretty independent issues. DITA might be wonderful if we had the time and resources... but until then, it's great to discuss and strategize around more immediate improvements to our system.
ps. DITA interested folks, you should really get in touch with Kevin http://groups.drupal.org/user/8367 - at DCSF, he was talking about a system that he'd built that might make a good starting place for the efforts and sounded open to sharing his work. - see previous discussion http://groups.drupal.org/node/64903
both efforts are not mutually exclusive
I agree that both efforts are not mutually exclusive: we can do ownership experiments AND keep in mind that hopefully in the not too distant future we'll be switching to DITA.
--
Check out more of my writing on our blog and my Twitter account.
+1
I like the idea of turning documentation sections into something similar of projects, where you have someone (or many) that keeps an eye on the content and as a worst cast can mark it as 'not maintained'.
I don't think there has to be an economical gain tied to get people interested in maintaining documentation -- I mean how cool wouldn't it be to be able to say 'I am the maintainer of the Views Bulk Operations documentation'? People are already contributing to the documentation, and being recognised for doing so wouldn't lessen the efforts from community members. But most importantly, it could help get some more structure and maintainance to the docs.
Those are my five cents!
//Johan Falk, NodeOne, Sweden
PS: DITA sounds interesting, but it also sounds like another discussion.
If I understand correctly?
To get this clear in my head:
It sounds like a good idea to me!
My background on Drupal docs: I've been dormant on the documentation team almost from the start because I never really knew where I could make an impact and really never had a map in my head where things were in Drupal documentation. Of course, those that have the map might feel it's easy, but I felt like I'd be exposing myself to be a moron to not immediately get how Drupal documentation is structured.
I've started to spend more time using the documentation to gain a better understanding of the gaps I have in my understanding, but it's still a bit hit-and-miss. I've taken the opportunity to start rolling in some comments as a trivial contribution.
People speak in whispers (and sometimes louder) about the death of the book module (someday) but does it live on solely due to Drupal docs? Could a suite of DITA modules/installation profile be a way forward?
Richard Sheppard
http://uk.linkedin.com/in/richardsheppard
DITA (Darwin Information
DITA (Darwin Information Typing Architecture) is a standardized way of classifying documentation "topics." It is a popular tool used by professional technical communicators. The idea is that if we create an installation profile that uses DITA, we would attract more people who have a real interest in assisting with documentation. It is not quit there yet, but people are making important strides (http://www.youtube.com/watch?v=bZdjbxNHpXk&feature=youtu.be).
Wikipedia provides a decent introduction to dita: http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture.
I thought though that there were plans to organize content with DITA using taxonomy on the new docs site.
Would it be possible to
Would it be possible to simply add a field to the documentation issue queue for the handbooks? This way we could link to the current issues associated with a handbook, and people would have an easier time keeping up on all of the issues for the handbook that they are concentrating on supporting. This might be easier than creating contributed projects for each handbook.
Unfortunately any
Unfortunately any restructuring of the handbook > issue queue interaction is going to need to wait until we're on docs.d.o - we don't want to do a hack and manually enter the sections, we want to have it automate and self-update to stay in line with the book structure.
Just like http://drupal.org/node/810508 it's not really feasible to be done until then, basically because the issue queue and the handbook will no longer share a domain, and this will have implications. (Or at least that is my understanding.)
What would be useful is a proposal on how you all think we could best divide up the handbook - ie. how many subsections, how would we assign responsibility, etc.
We'd also need a contingency process for what to do if someone isn't staying on top of their section etc.
This is a great time to hash out the details of:
A) What the most effective division of labour would be.
B) What changes need to be made to manage this (ie. fields on the issues, etc.)
C) Some general structure of how to manage assignments + contingency plans.
Just like
But at least we have no shortage on good ideas :)
I'm not sure if I want to comment on the redesign too much, because it is a big issue with lots of stuff I'd have to read up on if I were to really contribute anything useful. Example being I don't know why docs issue queue would be on d.o., nor do I want to argue why they should be on d.d.o. without knowing the whole story.
I'm not sure if this suggestion belongs here, or here: http://groups.drupal.org/node/98394. But regarding "A," however, could we use maintainers.txt here as a source of inspiration. The way it works as I understand it, is that as the document states:
My understanding is that these people aren't required by any law of Drupal too respond to all issues with their modules, but they probably do in many cases. Then there are multiple people listed for most areas, and people are also listed multiple times. But the idea being that more people would be willing to sign up if there wasn't a strong commitment. And if these people choose they could discuss, come to a consensus, and take an executive action over the direction of the particular handbook. I guess this is kinda like the mentors page, so maybe the discussion on this is already over.
I do like the idea of breaking things up more in a social sense at least. Some technical way to make it easier to follow would also help.
Indeed, indeed, good
Indeed, indeed, good points.
I suppose I am just saying appointing a single person to be "in charge" of each area of the handbook could be more detrimental than helpful... on the other hand, having a component per section could be great, as it'd be easier for people to track issues in their area of interest.
There is probably a really good improvement in here somewhere. (And yes, I love hearing and discussing new ideas!)
As far as the d.d.o issue queue question... I guess I should say I'm not 100% sure it's not being moved, but I haven't heard anything about separating it out of d.o issue queue, and it was implied that this was the reason why my issue re: nodereferencing issues to handbook pages and killing comments (http://drupal.org/node/810508) could not be taken on atm.
I suppose I will probably be able to learn more about the intricacies of this plan as time goes on and I get to talk to lisarex more, will make note to ask about that...