Hey fellow docs enthusiasts!
As some of you may have seen, there is going to be a big Docs Sprint in Vancouver in December (come join us if you're nearby!) The other part of what's going on that weekend, is that the core Docs Team members traveling here, as well as a few core devs (webchick, chx, and dmitrig01) will be gathering on Friday to discuss the Docs Team structure and initiatives in a dedicated retreat style afternoon.
We'll be discussing and brainstorming about things like:
- Handbook structure issues (larger structural + architecture changes)
- Handbook technical issues (overarching technical needs, tools, etc.)
- Handbook content (major holes in content, sections that need a ton of love)
- Ideas/changes for the API docs
- General ideas about Docs Team structure (how to manage/maintain subsections of docs, mentoring/recruiting, sustainability)
Jennifer and I would love some feedback here about some of the major overarching ideas you may have, or issues you see needing solving, so that we can add them to our list of what needs discussing. Stick to the big meta stuff here as much as possible, but bring it on!
Thanks in advance for your feedback!
Comments
On my radar: sustainable documentation
My big issue, which hopefully we can talk about in Vancouver, is in making the Drupal documentation sustainable. As of last spring, the handbooks had well over 6,000 pages of content (not including the API, Drupal Help, and archived material). That's a LOT of content and it's conceivable that the amount could grow substantially in the coming years. If this was a commercial product, it would take an entire documentation team (maybe as many as three or four full time writers, one or two editors, technical specialist, and manager) working year round (plus part time help at crunch time) to manage and keep current. So with only volunteers, it's really important that we adopt industry best practices with respect to keeping this manageable.
Some of the obvious things that need to be done are:
Single sourcing - We really have to stop doing multiple versions of the same content. This is one of the cardinal sins of technical communication and it's something that we really haven't come to grips with yet. The most obvious example is that we're writing separate descriptions of the same functionality for drupal.org and then doing it all over again for the Drupal help system. Fixes get made to one version but not the other. Even just within the handbooks there is lots of overlap and duplication.
Addressing this will take both technology (e.g. the ability to map the same content to different deliverables perhaps with some help from DITA) and a bit of a culture change.
Trimming the fat - Although the handbooks have some major gaps, an equally important problem in my mind is that they have become bloated, long winded, and unwieldy. This is a hard one to deal with because all this content has been contributed by volunteers with the best of intentions but there is a lot of redundant content which really should be merged or purged. It's a tough problem because there's a high risk of annoying people who have donated their time to contributing content but the overall documentation effort is going to suffer if we don't address this question. It's great to encourage a wiki approach and treat every contribution as valid, but really our focus should be on minimizing the amount of documentation so that there's less to be maintained (e.g. updated, corrected etc) and less for the user to wade through.
DITAmashup concept for Drupal documentation?
Hi, All --
I'm an experienced DITA consultant (both architect and practitioner) but new to Drupal and this forum. I've been reading the comments on the planning sessions for the future of the Drupal documentation, and Lee Hunter's recent comment caught my attention -- I've been there, also! Too many pages, too much information, duplicated content, etc.
I've been working recently on the concept of merging structured documentation (using DITA) and unstructured content that has been community-produced (or "crowdsourced"). There are pros and cons to each type which I won't try to summarize here -- but it's my belief that it is possible (or OUGHT to be possible) to combine the two types in a creative way and "have your cake and eat it too" -- a streamlined, vetted, minimalist, structured information collection that provides an information framework, PLUS the informal, valuable, "real-world" advice from the community. I call this information combination a DITAmashup.
It would take time to set up but I'm convinced it could work -- so much so that I'd be happy to prototype and demo it, given a reasonable amount of time and some coaching on what current content would be best to offer a meaningful proof of concept.
If this sounds intriguing to the doc team as they contemplate the future path of the doc, just let me know. My business partner and I are working on such an information collection using our own content and WordPress, and we intend to duplicate it on Drupal at some point. We'd be happy to help the Drupal doc team visualize the possibility of their own such collection if they're interested.
-Anna van Raaphorst
Succinct foundation and copious discussions...
I wonder what avanraaphorst has in mind, specifically.
Having succinct foundations and options for copious discussions seems one 'best of both worlds'.
With regard to Drupal core documentation,
does anyone like the idea of something EXTREMELY succinct,
while each page is also a (moderated) blog?
This has been the format of php.net, which all Drupal folks are familiar with...
Managing drift between Themer and Dev discussions
is always a Drupal challenge, but they prolly should share core docs, No?
Jeremy Donson
Database and Systems Engineer
New York City
Lee - Big +1's to both of
Lee - Big +1's to both of those, I can't agree enough that those are two huge issues we need to find some solutions for. You and I both know well what a beast the documentation is. I would also really emphasize the need for a better strategy for dealing with "archived" or old material... what we are doing now isn't really ideal!
Anna - Really appreciate the input and your keeping up on what discussions have been going on. I am certainly keeping an eye out for those DITA and technical documentation specialists that have been coming out of the woodwork lately, it's great to have some people who specialize in this to sanity check on what's going on. Please do keep providing feedback!
Ladders of Dependency in Learning Drupal
Project Managers and Themers and Developers and Sys Admins all need to learn how to
gather their pre-req skills and focus on their core strengths.
In support of Team Drupal, and in agreement with Lee's post for sustainability,
I wonder how to help people take the Drupal wow-Factor and turn it into a better guide for all team members.
Since Drupal platform CAN be customized to become more suitable for implementations, no single platform exists.
None, that is, other than core. All other features of Drupal depend upon core, literally.
Therefore, properly documenting D7 core seems the first step, beyond which all other steps will either benefit or suffer.
In this regard, migrating core from D6 to D7 and implementing new core features like core CCK and simpleTest seem paramount.
Also, migrating from other environments/CMS' seems like a wise avenue to pave.
Finally, referencing prior documentation may seem a convenience, but I feel a clean break with exceptions would be a better strategy.
With respect to all... Feel free to disagree, as I learn more that way. Thanks!
Jeremy Donson
Database and Systems Engineer
New York City
If you want to help with D7 core docs
Just re: D7 core docs... http://drupal.org/node/515870 is a list of the main core issues, or if you search for critical issues in the Docs queue http://drupal.org/project/issues/documentation that will cover a lot of the top needs. We definitely need help!
Orphan Pages
http://drupal.org/node/421676
http://drupal.org/node/433268
Could we have a periodic report to catch orphan pages? This initiative has been pursued before, but never to completion.
Thx bekasu - we'll add that
Thx bekasu - we'll add that to our list, sounds like a pretty small bit of work to help with Lee's decruft the handbook initiative ;)
My two cents
There are two things I'd really love to see happening on drupal.org:
Make it easier to include images in docs
Currently, only site maintainers can include images into posts. Because it's a security issue to include the
tag by default, this is hard to implement. However, with modules like http://drupal.org/project/insert it should be manageable. We also need a way to work together on images and be able to update them. Why do we need this? Example: http://drupal.org/node/171194
The image used here is great. And says so much more than words can describe. We need more images!
Add tagging to nodes
We could improve the ease to find content on d.o. by adding free tagging.
Kind regards, Baris Wanschers
Automatically promote to allow images after 1 month
+1 - davereid has suggested that we just automatically let drupal.org members post images after 1 month. That seems like a pretty good solution to me.