This is my idea of how Drupal documentation should be created. It is further explained in this forum topic - A Revolutionary proposal for creating documentation relating to this topic in another one Drupal documentation: A constructive criticism.

The right approach here is not for everything to be created at drupal.org, but for Drupal documentors to create a document outline, with chapters, topics, and desired content specified. Even this part of the process can involve the community.

Instead of real content there will be links to contributors websites, probably wikis, where their versions of the topics will be created. Readers can then vote on which ones are the best and Drupal documentors can select which of them will go into the Official Handbook, which may not necessarily be those with the top votes.

Drupal documentors can also create their versions, but in their own sandbox, which are also linked to just like the others. It could even be the case that some of the unofficial guides may be so much better than what the Official guys are producing that they may even decide to apply their efforts to those instead into the final Official version.

After some time each chapter or topic will be well fleshed out and the best ones can make it into the Official Handbook. If the manual can also be developed around a real or imaginary project, using a real website, such as the new.drupal.org, that will also help.

The approach here is for progress to be through small but well focused contributions, in well defined areas. Having thousands of cooks will spoil the banquet, it the cooks are divided into small teams with well defined tasks in preparing the banquet, you will end up with great banquet.

One thing that we have to realise that Drupal is a moving target and new versions may come about before the manual is completed. But so long as the Drupal version involved one provides a strong enough foundation for developers to work on, once they create a project with that version they might even stick with it for good where that project is concerned. Module breakage and all that.
In any case the links can point to the appropriate versions for newer an older versions.

My message here to Drupal leaders is: create the structure, setup some guidelines, provide some advice and control, and the community will do the rest.

Many hands make light work.

Just as with modules, business can sponsor some pages by providing staff or paying bounties to support their creation, and have their shiny logos shining out brightly from the pages if they want.

The Component selected was Developer Guide which reflects my area, but it is equally applicable to the User and Admin guides.

Comments

Chill35’s picture

Chill35 commented

My G** you STOLE my idea (LOL). I SWEAR I had this very idea today...

Really there will never be better doc out there than off-site (initially, when it's created), on other people's web sites, and in people's intended-for-publishing books.

I suspect that a few people involved in Drupal.org are working hard on the book that's coming up in April... NOT putting in their effort in improving the documentation here... (their right)... and don't tell me it's for the money, it's mainly for other intangible benefits AND money... lol...

drumm’s picture

drumm
he/him
Location NY, US
commented

I know a few technical authors. Writing a book isn't profitable in terms of money given the large time investment.

Good work on Drupal itself has come from Drupal-related-authors. They have to take a close look at the system for research and writing. That results in improvements to Drupal when they notice something that should be changed.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented

-1 to Drupal documentation being scattered all over the Internet on random sites that may or may not be online in a few months' time. This will only lead to link rot, fragmented data, and non-centrally searchable information. Ugh.

We have an outline already. It's called the handbook. Anyone can create handbook pages. Anyone who asks can edit handbook pages to refine and improve them. People are more than welcome to contribute stuff they've written on their personal/business sites. People are also more than welcome to collate links to off-site tutorials that are helpful. If you have an alternate outline idea for the developer's guide, propose it to the documentation mailing list. If your company wants to pay to have people improve the documentation in one area, propose that too.

Sorry, but I don't really see the point.

eaton’s picture

eaton commented

Instead of real content there will be links to contributors websites, probably wikis, where their versions of the topics will be created. Readers can then vote on which ones are the best and Drupal documentors can select which of them will go into the Official Handbook, which may not necessarily be those with the top votes.

Here's a secret: joining the drupal documentation team is not difficult. You do it by Clicking this link and typing text that explains something that was previously not explained, or not explained well.

There is a hierarchy already; there may be opportunities to improve it, but those are opportunities for specific changes, not a revolutionary new approach.

I have to concur with webchick; distributing the docs around the 'net is a recipe for more confusion and linkrot. Not only that, it would be nearly impossible to update outdated information if it wasn't on drupal.org. Any maintainer with the knowledge and dedication to maintain a separate off-site doc site, and keep it up to date, would be able to work just as easily here on drupal.org, with the added benefit that others could help them.

Chill35’s picture

Chill35 commented

You're right, Drumm. The benefits are mostly intangible. But indirectly they do help with getting more money in the end. Anonymously contributing doc on Drupal.org will only help yourself understanding the topic and it will help others but it will not help your career. Publishing a book will. Putting doc on your own web site will.

I wonder when IBM will update to Drupal 5 their Drupal documentation. Will they ? Do you guys know ?

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented

This is getting totally off topic now, but negative; I got my career from writing docs, helping out on forums, and writing/reviewing patches... all on dupal.org. Most other people I know of are the same.

I think most companies/clients who are truly invested in the platform are going to want to see people who contribute a lot to Drupal rather than their own ends when looking for a suitable employee/contracting firm. So contributing to drupal.org can help your career too. :)

greggles’s picture

greggles
he/him
Primary language English
Location Denver, Colorado, USA
commented
Status: Active » Closed (fixed)

(and even further OT we go!)

I also disagree with the idea that a "drupal book on your website" will get you a career.

The first question I ask when interviewing candidates is "So, what is your drupal.org username".

There are times when I blog about Drupal things outside of Drupal.org and at least some of that is in hopes to advance my "career". But you have to have a mix.

And I think there's a fundamental flaw with the original post so I'm closing this issue:

My message here to Drupal leaders is: create the structure, setup some guidelines, provide some advice and control, and the community will do the rest.

The message to contributors has always been "lead the way with your actions and, if the quality of your work merits, Drupal.org can be reshaped to fit into the new paradigm" (see, for example, planet.drupal).

Kieran has shown how to make handbook pages and have a tasteful ad for his company on them. To me that is the best way to go.

voipfc’s picture

voipfc commented
Title: Revolutionary, Innovative, Alternative approach to Drupal documenation? » Revolutionary, Innovative, Alternative approach to Drupal documentation?

I have a few points to add here.

1. The appears to be general consensus that the real issue is not the availability of good, quality information, but rather the ability to track it down in a timely manner. Having a clearly outlined chapter, sub chapter and topic outline, on a single page, as long and going as far down as it takes should be a no 1 priority. If it gets to long, some kind Web 2.0 nesting can be used to expand additional topics.

2.

Drupal documentors can also create their versions, but in their own sandbox, which are also linked to just like the others. It could even be the case that some of the unofficial guides may be so much better than what the Official guys are producing that they may even decide to apply their efforts to those instead into the final Official version.

Fair enough, I am willing to compromise on this one, the official docs can go in here from day one, rather than in a sandbox. But as my proposal refers to new handbook with a clearly defined outline, it could be that some topics are not in the official manual, but that others have created them elsewhere or maybe even at Drupal.org in a snippet or a forum post. The idea is that peer review is what gets them into the official version.

3. Page style
I made a comment in drapulled's forum post here http://drupal.org/node/106309#comment-185463 to illustrate a few complaints. If you are not in a clicky mode here it is verbatim.

Take a look here http://www.postgresql.org/docs/.

It is all clearly laid out and easy to read. It must be said that the technical proficiency of the contributors and users in their domain is much higher than with a CMS like Drupal.

A CMS has different aspects to it, database, html, themeing, programming and a whole lot of other things which have to be combined and it is unlikely be that simple. But you can see how properly outlined their documentation structure is. There is also a part where contributors links refer to off site pages, all clearly laid out.

What my proposal below describes is for a proper document outline to be created that both official and unofficial documentors can fill out.

There is also the issue of styling
Let us consider the style the official Drupal.org theme as an example. There are bold menus on both sides of the page to issues which for most of the time are not relevant to the reader's immediate interest and yet they attract attention by their very nature.

Without any formal or casual knowledge about design issues, even I myself know this is a no no.

At the very least the fonts should be normal rather then bold, and the user should have the option of hiding or minimising blocks they don't need.

The issue for me is more about organisation, style, layout and accessibilty of the content, rather than quantity and quality, which is quite good for anyone who is diligent and willling enough.

The real issue is having to spend 6 hrs looking for searching for info and waiting for responses on an issue that takes 20 minutes to implement when all the necessary info is located.
The time ratio definitely goes down as one becomes more familiar, but it is quite frustrating at the start.

PS. Can we have Gmail style nesting in forum threads?

Chill35’s picture

Chill35 commented

This is getting totally off topic now, but negative; I got my career from writing docs, helping out on forums, and writing/reviewing patches... all on dupal.org. Most other people I know of are the same.

I think most companies/clients who are truly invested in the platform are going to want to see people who contribute a lot to Drupal rather than their own ends when looking for a suitable employee/contracting firm. So contributing to drupal.org can help your career too. :)

You got a career not from doing anything anonymously : your contributions are from from being anonymous. I looked up your user profile and read posts that you signed. When you review or submit a patch, it's under your name. When you contribute on the forums it's under your name. When people create a module, it's under their name. That's from all this that that I formed a very positive opinion of yourself. A quite outstanding opinion of yourself I must say.

My comment I can understand can be taken negatively. But I think it's the truth. And that certainly does not mean that I will not contribute to the documentation. I am just making a general comment about the quality of things people submit anonymously. I think that people can definatelely get a career from contributing to open-source projects but it's far from anonymous in this case. I am really refering to anonymous contributions in the doc.

If you look up the most excellent documentation found on IBM, you will see pictures of the writers and their profiles at the bottom of each article. Douglass wrote (one part of) an excellent book published at Apress, under his name. Etc.

I agree though that my comment does not help or encourage.

Best regards,

sepeck’s picture

sepeck commented

Handbook contributors are listed here: http://drupal.org/node/14205 which is found on the main handbook page here: http://drupal.org/handbooks

Those active in contributing to the community in effort are in fact noticed, remembered and benefit. The reverse is also true.