Why Is Writing Drupal Documentation Harder Than Writing Wikipedia?
I used to write on Wikipedia, years ago when it was a wild frontier, we had barely 30 thousand articles, and not even my geek friends had heard of it from a source other than my blathering on about it.
It was quick and simple, deserving the origin of its name [1]. And it was quick not just to edit the content of pages, but their place in hierarchies and their order within lists. A whole section of the site that wasn't to our liking could be rejigged in a handful of browser tabs. Pages didn't belong to anyone, but the edit history and the attached talk pages gave you a clue of who was involved, and once you'd made edits to a page you could spot it in the Recent Changes list or your personal watchlist of bookmarks.
Now over to Drupal handbooks, where I find the process slow and laborious and confusing. I ask myself (and you!) — why?
We have Recent Changes of a sort: the tracker; we even have a tracker just for documentation changes, but I forget it exists because it's tucked down at the bottom of the site blocks. We have page revisions and diffs of pages, just like Wikipedia.
The differences I can see are:
1. HTML is slower. I know purists dislike wiki markup, but it's undeniably quicker to type ''italic'' and [[clean URLs]] than to muck around with opening and closing tags and finding the right URL. Granted, there is no one standard (though I would say that used at UseMod comes close) and Wikipedia has now bloated it so much with complex syntax to create all manner of things. But the handful of basic wiki syntax elements are good.
2. Structure is divorced from content. It's very handy the way Book module builds menus and trees for you. But it makes moving a page to another part of a book feel like a big destructive (and irreversible?) act. Furthermore, only a small number of admins can change the order of child pages, something which frequently makes all the difference between a clear read and a mess. On wiki, structure ''is'' content (italics, remember?): you want to make a list of child pages? You write a bullet list of page names. You want to move a page to a different part of the hierarchy? You just find what links to it and edit. Granted, this can often lead to an almighty tangled mess; not for nothing it is the full term a 'wiki-wiki-web' — not a tree.
3. Every article has an associated talk page. One day you find a section has all been changed and you're confused as to why? Find the answer in the talk page. You're pondering a big reorganization yourself, and you want to make sure other writers who are interested in this page get wind of it and have a chance to discuss it? The talk page. It's a bit more anarchic to what we're used to on drupal.org, but it keeps the discussion and the document side by side. I'm only an occasional participant in the documentation team, I'm not on the mailing list[2] and so I often find ''everything'' has been turned upside down and I can't fathom why, and I can't tell if it's work in progress that I should help with or just an almighty mess. Talk pages aren't perfect, and it's hard to follow discussions spread across many places, or even to know if you might be missing something. But there is an immediacy about the 'talk' tab at the top of a page.
4. Lastly, on Wikipedia it felt like there was a collective ownership of pages and sections. On drupal.org, I feel I'm treading on toes if I make too many changes. I don't know why that is; maybe we don't have the critical mass of documentation editors to turn into a community.
In conclusion: I don't have answers. I know that editing and more to the point, organizing our documentation is a big job, and I think the tools are not quite up to the job. As a first step, we should make book hierarchy editable by the documentation team. After that, start upon the inevitable debate about wiki syntax, and think about ways to better tie isues to the documentation pages they are about.
Footnotes:
[1] 'wiki' meaning 'quick' in Hawaiian, coined by Ward Cunningham for the original wiki.
[2] I hate mailing lists. Don't get me started on them. The 1980s called: they want their communication technology back is all I'm going to say.
I agree
I agree with your comment about lack of confidence - I've been using Drupal for close to three years, but my experience has intensified in the last 12 months. All the same, I'd be petrified to amend a Drupal handbook page because a) I wouldn't want to put on information that was inaccurate, and b) I wouldn't want to get slapped down by a more experienced Drupaller.
yeah, I see what you are saying
-1 for there being any inherant advantage of wiki-markup over actual HTML. I speak HTML now better than English to express what I want to say, and a friend recently pointed out how awful true wiki-code has become (not that I tried too hard to learn YetAnotherMarkupLanguage before now.
+1 But I totally see what you are saying about the ownership issues. But that's muchly an attitude thing. I know I an hesitant about 'stepping on toes' when reviewing or revising stuff that other folk I respect have edited, and there is a feeling of 'ownership' on pages I (or others?) have mostly done on their own.
So I check a revision history. If I see 3 or 6 different editors have already touched a page, that means it's part of the organic doc project, and if it needs rewriting, so be it.
The major real issues with drupal docs vs wikipedia are cultural, not technical. We have wiki+comments which is a bit of a hybrid. Any large structural stuff usually comes through the d.o webmaster or doc queues for feedback. I follow them.
and even now .. I wonder why I'm replying on this off-drupal blog instead of the d.o doc queue. :-B
HTML and Talk
I have to say, I hate Wiki 'markup'. Put an HTML toolbar at the top if you want to be quick! If you're using Drupal as anything more than an end user you should know some basic HTML anyway, no? <em> </em> is really not that much typing!
While the value of having a Talk page associated with a document is clear, the way Wikipedia manages it is a colossal mess. Good idea; terrible execution.
Documentation is not usually for the hobbist
I agree with you Tom, ownership and the latest version are amongst some of the most challenging aspects to trying to help.
An assumption I have made about the Drupal community is that a large portion of the community users are not programmers by trade or have had an education in software development. People can be great developers without education, and can be very organized, but best practices that get enforced often in schooling will show results in the code developed.
Also contrasting examples between one function and the next could provide good additional information. An example of this is in the PHP.net documentation. Users put good snippets of code and examples for the related function. --Personally, I find that very useful for those who are learning.
Perhaps if keeping up to documentation is a problem, integrate it into the work-flow. If the bug is fixed, before it can be closed, document it.
I don't like wiki syntax, usable sure, easy sure, but a step backwards because mediawiki for example had to create their own syntax.
agreed
I completely agree with all of your points except for #1. Maybe if you are used to writing in wiki style it is easier, but for me it takes about 4x as long to write a wiki page than the equivalent HTML cause I am not use to writing in that format.
I do a lot of editing on
I do a lot of editing on drupal.org and I agree with a lot of what you're saying. In fact there are a bunch of ideas which I'd like to steal from Wikipedia like watched pages (it just seems so wrong that I can't flag the pages that I want to track) and the free form "categories" taxonomy system that would allow one piece of content to be used in multiple hierarchies. I'm not so sure about the wiki syntax. It's definitely easier to use, but HTML is not really a barrier to me.
I'm not sure why you'd feel that you can't make lots of changes without treading on toes. My impression has always been that most people don't notice and those that do notice are thrilled to see stuff get done.
I think the toes thing is
I think the toes thing is that I don't get an impression of what other people have tried to do, or are trying to do.
As for wiki, it's not an outright barrier, but my enthusiasm flags a little every time I had to make a bulleted list; they are so much easier in wiki syntax!
Spot on
I've been programming for a long time, a lot of that time I've been working with PHP. I have happily contributed to loads of wikis, some of them I've started myself. I've been working with Drupal for about 1,5 year now and I've created many websites with it - and worked on a few existing sites. BUT I haven't found myself able to feed much back into the Drupal community yet, and the points you bring up here are the some reasons for that - it seems tedious and it's unclear to me where to start, compared to working on wikis.
(The main other reasons are the use of CVS and the silly bug tracker...)
Books are an obsolete
Books are an obsolete technology anyway. Does anyone read the Drupal documentation chapter by chapter, section by section? I want my information served in hyper-links, thank you!
Books only exist because paper has to be glued one page at a time. We don't have this limitation.
You're right about everything concerning Wikipedia. It truly is a common information collection because it allows commoners to edit the information.
Good post; here's my $0.02
Thanks for the insight. I hadn't really considered the benefit of having an associated "talk" page. But now that you mention it, it seems huge.
The "ownership" issue is the biggest one, IMHO.
Here's an example that illustrates both of these issues. I contributed in a small way to an issue related to README.txt documentation. It's a fairly small document, but the issue is now pushing 100 comments (!) and multiple patches. The process frankly scared me away from jumping back in. For one thing, I couldn't easily keep track of what the most-recent version was; for another, too many cooks had taken ownership.
The Book module always struck me as a "proof of concept" thing, to show that Drupal *could* do structured documentation, but not really a full-fledged solution. I think it's remained (semi-)popular mostly because of its branding: Everybody wants to write a book! :) But I don't believe I've ever seen a situation where it was a better solution for documentation than a wiki would be -- including on d.o. It's a shame.
Post new comment