Towards Docs Sustainability

We encourage users to post events happening in the community to the community events group on https://www.drupal.org.
arianek's picture

Compiling a bunch of the ideas that have come up over the last week in discussions with the Docs Team folks at Drupalcon London. It's been a running theme that the docs are no longer manageable, and some concrete suggestions to deal with that are as follows. Note they are all options and need not all be adopted, some are exclusive of others:

  1. Rejig role of online docs co-lead (API/dev docs co-lead need not change) to focus only on larger goals/planning and leave time for writing, and no longer responsible for issue queue gardening (aside from fielding docs admin requests). Make other Docs Team members (not Docs leads) responsible for day-to-day work in the issue queue reviewing, editing etc.
  2. Divest "handbook" completely from being a responsibility of Docs team and turn it into the "Community Wiki" which is unmaintained officially by the team. Write a curated central guide from scratch (possibly based on some other existing content) which is then maintained by a small core group of official docs maintainers. Keep this smaller guide concise and up to date.
  3. Improve infrastructure: This ranges from medium sized tasks like implementing node-reference fields and configuring blocks of related content, to an enormous overhaul of the structure of the docs into a system using XML or RDFa for example to make content reusable/structured. Lin Clark has some interesting ideas about this for making off-site docs searchable (see below).
  4. Recruit a TON more people: Through some kind of marketing (?) recruit and retain more and more active Docs Team members.
  5. Separate current docs projects: I believe Randy Fay originally suggested this - make each docs "guide" into a separate project, with its own issue queue so people can more easily work on specific guides (and even have per-guide coordinators). We currently just use issue tags to track different topics.

Personally 1-3 seem like the most sane, sustainable, and achievable options.

Pasting some other ideas from my blog that were docs-centered. Let's try and figure out what plans we like best and then create some actual issues for the docs infra or whatever is needed. Once we have those, we'll have to run anything huge/major by Angie and/or Dries. Please post your feedback below!

From Lisa Rex:

Controversial thought: why is Drupal.org expected to maintain stellar documentation? There are lots of great how-to resources out there on personal blogs, organization sites etc. What if ... you only maintained the central guide and allowed the community to furnish links to their content? I know it's giving up control, but that's exactly what needs to happen anyway. Seems like a lot of would-be contributors are still not shy about contributing documentation to d.o. but they are perfectly happy to do so on their own site...

Maybe a Planet equivalent for Docs contributions? Hmm.... (of course, it's not easy to search / browse except by Google, but bottom line, current process is unsustainable).

I am totally happy to help recruit but I am still not sure the onboarding process is clear. I have plans for a single page that helps people find a way to contribute, based on their skills/interests:
http://drupal.org/node/1010262#comment-4854318

From Lin Clark:

Well that's a funny coincidence, I was just telling Ariane on Tuesday about a project idea I proposed to Kasabi.

Basically, there is a pretty easy way that we could turn Drupal Planet (or a docs version of it) into a database. We could create a custom field that people could attach to their blog post content types. This would autocomplete with project names from Drupal.org. People could then say which projects their tutorial is about.

We can then make this information accessible to processors using RDFa or microdata. Once we've done that, a tool like Kasabi can create a database out of it. It's a particular kind of database (called a SPARQL endpoint) that is accessible over the Web.

This means we can then use Views to run queries on the endpoint. So if I wanted to show all the tutorials from Drupal Planet that dealt with microdata, I could just create a View with a filter and they would be listed on my site.

We could create additional facets besides the project, like whether its Beginner, Intermediate, or Advanced. I'm not sure what other facets would be helpful, but would be happy to hear from other people.

From Richard C:

Great idea here.

Doc teams are curator and editor, writing task should be minimal to necessary task.
And frankly, I think get rid of outdated and bloat docs is more fun, more fruitful than to write a new one now.

Replace them with those from Drupal planet, video(with automated scribe note), screen capture tutorials out there one by one, small part a time, is more hopeful!

See:
http://wordpress.tv/
See:
http://buildamodule.com/
Better,see:
http://www.khanacademy.org/
(This is almost the whole math principle of mankind in one page.)

So, for Drupal one page to maintain is more than enough! It a waste of energy, use technology! Else, outsource them.

Thanks!

Comments

Good stuff

schiavone's picture

I've been lurking for a while now hoping to be able to contribute. You've addressed a few barriers I've experienced outside of my own constraints. For me a lot of the barriers involve changing work habits to match the existing un-process. Another barrier is the lack of a central entry point. Love the Tuesday office hours. Love the wiki idea. Building up the org chart makes a lot of sense. To help recruitment maybe some of us could dedicate some user group meetups to Documentation.

Fix #3 and #4 will follow

LeeHunter's picture

Rather than trying to get Drupal insiders hooked on documentation, let's get documentation outsiders hooked on Drupal.

There are tons of people in the world that do technical communication for a living, but unfortunately very few of them have even heard of Drupal. That's because Drupal, as a general purpose CMS, doesn't quite cut it for the specialized needs of this group, at least not without lots of customization.

However I think that picture could change a lot with the work being done recently on things like conditional text and DITA, which will help make sole-source content possible. I strongly believe the best return on investment would come from creating a Drupal install profile that gives the tech-comm community an outstanding open source solution out of the box. Aside from solving some of our own technical problems on d.o, it would reach out to exactly the right community with the skillset and mindset to help with our content.

succinct code and succinct docs that stay current....

jdonson's picture

The lack of effective technical learning is both opportunity and crisis.

INQUIRY: How can we better ride two parallel moving targets we see here?

  1. Code changes and their platform impacts.

  2. Documentation that also is to reflect these changes, hopefully succinctly.

These two moving targets yield GREAT confusion to anyone jumping in.

This is an EPIC educational fail.

I suggest that we rely LESS on language and more on graphics for docs.

This would facilitate a more international audience with LESS ambiguous language.

Graphics of the underlying mechanisms are easier to understand than pages of code.

If I could say all of this pictorially, I would,
as it would support a more int'l approach to open source technology.

IF/When the docs and the code are equally succinct and effective,
THEN we will have crossed barriers that most do not even see at present.

Jeremy Donson
Barnes & Noble (book.com)
New York City

Jeremy Donson
Database and Systems Engineer
New York City

Less graphics please

LeeHunter's picture

Graphics are useful at times but they do introduce a host of problems that actually make documentation less, not more, sustainable:

  • They are much more difficult to execute well.
  • For a number of reasons they are more difficult to change, correct and update: the original source files get lost, people use many different graphics programs that don't always have the same capabilities and features, people use different screen resolutions for their captures etc. Changing a bit of text in an HTML file is trivial, changing even a tiny bit of a graphics file can be challenging for anyone but the creator of the graphic (assuming that person even has the same files and software handy at the time they want to change it).
  • It's harder to maintain consistency. People have wildly different ideas of what looks good.
  • It's harder to do translations (screen captures need to be redone for the target language, as do callouts and labels)
  • It's bad for accessibility unless the graphics are carefully annotated. Which in turn means that it's easy for the graphics and the metadata to get out of sync.

All in all, graphics can be a maintenance nightmare and shouldn't be used unless it's clearly the best way to make a point.

While you make a whole host

greggmarshall's picture

While you make a whole host of points, many people are simply visual learners and a picture often conveys more meaning, faster than even a well done description. There's a reason the quote "a picture is worth a thousand words" has been very popular over the years.

Isn't there some hosted/open source solution to creating the pictures that could address some of the issues you bring up?

that depends

jdonson's picture

Hi Gregg,

It depends upon how we frame the "issues".

I certainly have a confessed NYC-educator perspective
and as open source engineer I want to see this get organized.

As a dev tech example,
I created the diagram for the Token module: http://drupal.org/project/token
It required the approval of Greggles, the module maintainer.
EVERY Drupal core module should get the same treatment.

Overall, I would suggest that defining and sequencing questions is very helpful.

We might do well to both define discrete problems and prioritize / weight them.

I see this breaking down into several areas:

  1. Expertise of Trainer with regard to Industry and Platform (be it Drupal or otherwise)

  2. Current and Intended Role of Learner:

    [user, creative, editor, themer, dev, sysadmin, dba, content manager, biz mgr, testing, etc]

  3. Tools for Imaging

  4. Tools for Language, including glossary and localization.

  5. Clear definition of differences between Module Devs / Integrators
    and UI Designers and Themers

Regardless of Myriad Questions,
Some Answers:

  1. cacoo.com

  2. pixlr.com

  3. semantic wiki

  4. better use of jquery for docs - this will be discussed further soon

  5. formalized structure / approach is needed
    for presenting docs at varied levels of abstraction and detail - also tbd further soon

If concrete examples would help, lemme know.

Thx.

Jeremy Donson
Database and Systems Engineer
New York City

If, you can outsource graphic

Clean's picture

If, you can outsource graphic work. You still think it is a good idea?

For example, find a docs topic that you can do screen capture/quick sketch.
And give them to me. And I do the rest. Is it ok?
(Of course, just for demo. You still need to get a team to do and maintain it.)

I think some graphic parts can be systematize too, not sure how drupal.org infrastructure work, because we are not aim for beautifulness here. But at the end of the day, it depends on what docs team feel happy and can be productive.

But I still think docs team scope should be collect tutorials, useful comments from everywhere and focused more on structure them.

insourcing...

jdonson's picture

I am talking about building a team of both software engineers and ui designers.
That should include graphics people and docs people.
It can be a very lean and mean team.

I am a trained Software Architect and Database Administrator. Indeed, Structure Counts First.

Good And Current Example:

QuickStart Guide is a good thing,
because it establishes a format where the goals are not overly ambitious.

The structure of a QuickStart could be discussed forever,
but there is not enough time for that.

So, quickly, the goals and methods and payoffs of such a QuickStart structure are worth considering.

Goals: Brief pictorial walk-thru for beginner to get a recipe or brief lesson.

Methods: As per topic and audience.

Payoffs: As per topic and audience.

NOTE: The fewer the new words, the easier it is to teach and localize. Graphics makes that easy.

** Crucial questions regard how to extend api.drupal.org to support better training for devs.

This should start with the Drupal 6 and 7 core 5 modules: user, system, block, node, filter

All of Drupal functionality depends upon these functional units of php and mysql code.

Though they both use php and are crucial to CMS,
Module Devs and Themers have completely different skill sets and job roles and workflows.

In addition to being properly-suited for a given industry,
training for Module Devs and for UI Themers should vary accordingly.

Themers are concerned with look and feel and UI.
Their mandatory prerequisites are: html, css, jquery/php, graphics

Developers are concerned with functionality.
Their mandatory prerequisites are: advanced php, mysql, unix

The software specification formats that they require reflect the differing concerns of these roles.

These two roles could be served by one person,
but not for long in a growing organization.

Jeremy Donson
Database and Systems Engineer
New York City

Feedback about graphics

arianek's picture

Feedback about graphics noted, though like Lee said, it poses some very serious problems for maintenance.

If anyone has some more feedback about the options in the initial post, please keep it coming!

Make other Docs Team members ....

Sree's picture

Make other Docs Team members (not Docs leads) responsible for day-to-day work in the issue queue reviewing, editing etc.

This is definitely a good idea - there are many people in the community who are willing to take challenging responsibilities but, they lack required permissions etc etc.It would be a good idea to get more people involved into more responsible roles.

Sree

The only permission lacking

arianek's picture

The only permission lacking is the image embed permission (and access to pages with images) which require docs admin role (which over 300 users currently have).

There is an issue in progress for this http://drupal.org/node/528682 if you want to watch it or help out.

Otherwise, there's nothing at all stopping people from taking on more day-to-day work, so just dig in!

Thoughts...

wfx's picture

@arianek I was just working on a theme for a freelance client who is also a Drupal developer and the topic of documentation came up. What he said surprised me, he said, "documentation should be automated, it should write itself. Someone just hasn't made a script for that yet."
That really took me aback because I think there is a subconscious expectation in the community that that will happen, there will be some kind of script-bot that will recursively go through and solves all our Documentation needs. No humans need apply.

At my main job my role is Web Content Producer for a university IT department where I build pages in Drupal, maintain content, build forms, views, update modules, and generally unbreak things as I find them in our aging Drupal 5 site that's about to be upgraded to D6. That's my skill set. That said, I really don't know how I can contribute here because the model seems to be to go out, scour D.O. to find areas where information is lacking, and author documentation. Only the places I would think to go seem to be covered. Is there a central list where I can go and get assignments? I discovered the Current documentation Priorities page tonight, is that the closest thing to an assignments page we have? I've tried the issue queue before but most of the time the issues I could work on are already done when I find them and what's left is beyond my level of expertise (I'm not a Developer). Several experiences like this left me wondering what new people could do.
Inevitably there will be some resource I missed so if I've overlooked some pages outside the "How to contribute to documentation" and "Quick ways to improve documentation" pages please send them my way.

Many thanks,
Kevin

p.s. I'm responding because of #4, "Recruit a TON more people" :)

Thanks!

jhodgdon's picture

I've been away in England for a while, away from Internet... just want to say that I'm generally on board with what Ariane is proposing.

My thoughts:

The problem (as Ariane stated above) is that the current d.o documentation is not sustainable. The members of the docs team (and especially those who have taken a leadership role of any sort) get overwhelmed by it. We have something like 4000 non-archived pages, and not all of them are relevant or current or correct. It's just too big of a hunk for one person to oversee without quickly burning out.

I don't think that improving the infrastructure for the current d.o doc will help much of anything. We can make comments go away and facilitate filing issues instead, but that will not magically improve the docs or make them smaller. I'm not saying we shouldn't have better tools, but I don't think it will really help the sustainability issue or the burnout issue.

So I think we need to acknowledge that the d.o docs we have are currently a Community Wiki. Let's make the infrastructure better so that the community can keep wiki-ing to its fullest potential. And if having overseers for the various books in the Community Wiki makes sense, let's do that.

And let's start a new site that will serve as both inline and online docs for Drupal -- a smaller site without "Add a child page" ability -- where we decide what docs we need and create/copy in only those docs. We'll make it DITA-ized (small modular topics and multiple outlines), and make it importable into a Drupal site you're building -- more details on this here: http://drupal.org/node/1095012


On another note... I think we need to think as a community about what kind of docs and web site we should have at drupal.org. Who is our audience for Drupal docs, and what is our responsibility to them? How much do we document? Or should we even have our own d.o drupal docs -- should we instead just have Lin Clark's repository of outside docs? I was approached by people from Acquia and NodeOne (and others) at DrupalCon -- they have good docs out there, and would like to make them available, even on drupal.org maybe, but only with attribution (i.e., they want to be acknowledged as the owners of the doc). What would this mean -- would they maintain the docs or just contribute them and go away? Obviously this doesn't fit with our current docs model (no "owner" of a given page)... but would it be better?

Anyway... maybe this last bit is out of scope for this page, and I know I'm rambling, but wanted to say something -- feel free to redirect to a new thread if it's out of scope Ariane!

+1

Itangalo's picture

First: Huge thanks to you and arianek for taking the lead on such a large and important project as the docs. You are brave heroes.

Second: I think the original post summarizes the docs problems pretty well, and I can only agree that recognizing the current docs as a community wiki will help it improve as such.

Third: Just so that I wasn't misinterpreted at DrupalCon – I would be happy to provide any documentation I write without attribution. My goal with making Drupal docs is to help people learn Drupal, not making money or fame, and if attribution gets in the way of spreading documentation then I don't care about attribution.

Cheers!
//Johan Falk
**
Check out NodeOne's Drupal Learning Library! 150+ screencasts and exercises, for Drupal introduction, advanced configuration, and coding. <-- published under Creative Commons license!

Wasn't you...

jhodgdon's picture

Johan -- thank you for your generous offer! it was people from the Training part of NodeOne and a couple of other companies who were interested in maybe contributing their training curriculum materials to d.o with attribution.

Anyway... I think that we'd probably be better off linking to them than adopting them, in general, but I haven't seen the docs they might be interested in submitting, so who knows.

Thanks :)

arianek's picture

I thought as much Johan - keep me posted on whether the publisher rights will be an issue. It's an extremely generous offer from you - I've read some of the book and I think it (or parts of it) would make some excellent content for a curated guide!

+1

Itangalo's picture

Double post, sorry. (Damn train connection!)

@jhodgdon: I was approached

Sree's picture

@jhodgdon:

I was approached by people from Acquia and NodeOne (and others) at DrupalCon -- they have good docs out there, and would like to make them available, even on drupal.org maybe, but only with attribution (i.e., they want to be acknowledged as the owners of the doc). What would this mean -- would they maintain the docs or just contribute them and go away? Obviously this doesn't fit with our current docs model (no "owner" of a given page)... but would it be better?

I have started this thread: http://groups.drupal.org/node/171059

Sree

Future doc work

avanraaphorst's picture

I agree that our intrepid leaders have taken on a huge task, and I appreciate all they do, as well.

Thanks for the response to my suggestions and offer to help the cause. Over the next week or so I'll take a look at how Dick and I can contribute here are also keep up our other obligations, and will post our intentions for comment and to avoid duplicate work.

One question (but no hurry on the answer): Is there a target date when drupal.org will be converted to D7? We are working exclusively in D7 and don't want to have to deal with both releases at this point. We're hoping D7 will be in more common use by the end of 2011, although it does seem so far that it's lacking some pretty important contributed modules that haven't been converted yet. Does it look like there will be a clear split between the D6 and D7 doc efforts moving forward? (It seems that way to me, but maybe I'm not that good at interpreting the strategy and plan yet.)

D7 on d.o

arianek's picture

There's no way to say for sure, but I don't think it'll be soon. You could try asking someone on the infra team or the DA if you want a more specific idea. I think we'll be lucky if it happens in the next year, so if you want to help maybe better to find another area, or concede to working with D6 for now. You kinda have to work with what is there if you want to help, since there are no assured delivery dates or funding to make most work go faster.

Whether D6/D7 docs will ever be split depends on how the infra progresses, it's not something we can clearly predict. Again, better to just find a place to help than wait on the conditions to change.

Proposal

jhodgdon's picture

Here's a formal proposal (draft! comments welcome) for how to restructure the d.o docs and the docs team responsibilities:
http://groups.drupal.org/node/175174

Respecting the redactors

Fiable.biz's picture

Recruiting redactors is not enough. Not to have them give up, the bosses should respect our job. The 1st time I contributed, adding information about the multisite installation on Mandriva Linux on an already existing page, the page got archived within a few months, without warning or explanation. I then just arranged it a bit and copied it to Mandriva's wiki, where I could add pictures (I never understood if it's possible to put pictures on Drupal's documentation and how, but the fact is there are very few.) and when it still is and looks much nicer than on Drupal.org .
Another point is the benefit. Companies could probably contribute more if they could get some benefit from it. So signed pages could be an excellent idea. There are signed modules and signed themes, why not signed documentation? A rule could be that when the page got substantial modification(s), the signature be erased. Or that a signature be automatically deleted after 1 year if the main author didn't update it. Or just that too old pages be archived (which is already the case), so that, to get one's name on a page for a long time, the authors should better maintain them.

I love Lin's idea about

laura s's picture

I love Lin's idea about building a database of content that's aggregated. It would be a big value-add on top of rationalization/organization/rearchitecting of d.o documentation.

Laura Scott
PINGV | Strategy • Design • Drupal Development

Documentation

Group categories

Event type

Post type

Group notifications

This group offers an RSS feed. Or subscribe to these personalized, sitewide feeds: