Home / Comment permalink

Acquia Documentation Survey - Results - The Way Forward

Acquia Documentation Survey - Results - The Way Forward Many thanks to all who provided feedback in the recent survey about Acquia’s documentation. Here are the results of the survey’s multiple choice questions and some of the conclusions we have drawn from them. Question 1: "Have you ever used Acquia’s documentation?" Just under half the survey respondents said yes. - Acquia’s overarching mission is to improve Drupal and make it accessible to the broadest possible audience. In this vein, the primary goal of Acquia’s freely available documentation effort so far has been getting new users from zero to up-and-running with Drupal. If half of survey respondents have used our documentation, it is meeting a need for simple, focused, compact Drupal documentation. Some of the direct feedback we’ve gotten also confirms this and has given us some good ideas for future directions to take it. Question 2: What kind of documentation should Acquia publish?
  1. Just over two thirds consider "how to" instructions important - It is great to know we’re helping people on the "getting new users up and running" front.
  2. Just under two thirds of respondents consider site and feature recipes important - This is what we call "taking it to the next level" for new Drupalistas and this is where we see Acquia’s next documentation focus.
  3. The (large) majority consider module and core documentation unimportant.
Question 3: In which formats should Acquia’s documentation be available?
  1. First place: online HTML - This is our main format and is always the most up-to-date version of any given documentation. It also provides a perfect platform for expansion into enriched formats such as screencasts, slideshows, and so on.
  2. A close 2nd: PDF - Many users want the convenience of documentation accessible offline. We are using a set of open source tools to semi-automatically generate PDF snapshots of our Getting Started Guide approximately once a month. Given the popularity of the format, we are considering expanding this offering slightly to include smaller PDFs of individual chapters or topics from the guide; tutorials; and perhaps materials such as the documentation on Acquia Search, the SVN repository, etc.
  3. A distant 3rd: offline HTML/helper apps
Question 4: "General feedback on Acquia's documentation: - What do you like? - What is missing? - What could be better?"
"Why duplicate things? Wouldn't it be better to just contribute to the documentation on d.o?"
"Why on earth is there an Acquia documentation team? Why isn't the Acquia documentation team improving the docs on Drupal.org and then aggregating in the appropriate pages to build their own manuals?"
Discussions in the Drupal community about documentation have been heating up lately. I take this as a good sign - passion about the project is growing beyond code issues to include usability, design, documentation and more. The documentation discussions include analysis of the current state of drupal.org documentation (whether it is "broken" or not), what can be done to "fix" it (if it is indeed broken), calls for putting up or shutting up, and most importantly for Acquia: the role of community documentation vs. 3rd party documentation. Responses like this really helped us gain insight into what we are doing and why. This goes to the heart of our mission to improve and promote the Drupal project as a whole. Commercial enterprises committed to open source projects have special problems and special responsibilities. Any Drupal company worth its salt should be working very hard on finding ways to give back to the project. We are not selling secret sauce, we are all offering a growing palette of Drupal services and expertise. At Acquia, we believe that a focused, targeted approach to documentation - freely available and applicable to any Drupal 6 installation or site - adds real value to the Drupal project. Acquia’s documentation is not in competition with that on drupal.org, just as Acquia and Acquia Drupal are not in any kind of competition with "drupal.org Drupal". Drupal.org, whatever its strengths and weaknesses, remains the deep repository of our community’s vast knowledge and experience. It is an invaluable resource to thousands of us every day.
"More tutorials, videos, etc. for the beginning Drupal user. ... users new to Drupal need direction and documentation from Acquia."
"I am very new to Drupal and right now for the past week I am suffering from Information Overload. There seem to be several pieces of the puzzle in various locations online, and different versions or drupal "how to" pages."
During my own first attempts at installing and configuring Drupal (4.7), the "signal-to-noise ratio" for me on drupal.org was overwhelming. Not knowing all the jargon, I waded through the site, hoping to stumble on whatever simple configuration information I was hunting for among the gnarly, hard-core stuff. Although the depth and incredible value of drupal.org’s information has opened up to me as my knowledge of Drupal has grown, the drupal.org remains daunting for newbies. Acquia's mandate is to make Drupal easily accessible and attractive to as many people as possible. Our documentation, Getting Started Guide and helpers like the stack installer - that lets you install Acquia Drupal in a few clicks - help new users get started with Drupal as painlessly as possible. Packing a large suite of community modules into the Acquia Drupal package and also putting the whole thing into an SVN repository help both beginning and more advanced Drupal users spend less time downloading modules and more time on other parts of building their sites. With that in mind, we want to create an information-offering comprising both documentation and a knowledge base that include easy to find, focused, essentials for:
  • new Drupal users
  • those wanting to shop around and compare Drupal to other systems
  • Acquia’s subscribers, partners, and users of Acquia’s special products and features
  • the Drupal community at large
This all could include common troubleshooting issues that come up for our support team, site/feature recipes, alternate configurations, and so on. Acquia’s documentation will move beyond essential installation and configuration materials. The way forward will likely lie in presenting solutions to common problems, materials to help users move from Drupal beginner to proficiency, and help for more advanced users and developers. Respondents also said:
"More tutorials, videos, etc."
"screencasts can be tremendously useful"
"Now is the time to start documenting site recipes, so that users can get the _kind_ of site they want."
This confirms the need for the "taking it to the next level" material mentioned above. For example, after getting through a successful installation with the current documentation, users have a working but empty site. Feature recipes seem to be a logical step. These could be as simple as "How to start blogging" and "How to add another author to my site" or as complex and multifaceted as "Moving between servers: live, dev, staging, production, test, local, remote ...", which could take dozens of tutorials to cover. What would you like to see? We are very interested in hearing back from you about what topics and feature recipes would interest you. This information can help guide where all this is going.


Posted on by tgeller (not verified).

The (large) majority consider module and core documentation unimportant.

I find this very interesting -- and somewhat unexpected. But it could point a way to make the drupal.org documentation much better. 

In my controversial post about documentation, my point wasn't to destroy what's there -- although of course that's what people apparently thought when I used the phrase "burn it down". Rather, the point was to clear the way so that drupal.org's documentation becomes manageable.

It needs to become manageable for both its creators and its consumers. We've all heard complaints from the latter -- that finding the information you want is difficult, if not impossible. But the site's complexity has also turned me off from contributing: I don't want to write something that might already exist (because I can't find it), then spend 10 minutes finding the best place to post something, only to still believe it'll never be found!

But survey respondents suggest a focus that drupal.org would fill very, very well: module and core documentation. Consider them like administrator APIs: They give the essential, functional information, without muddying the waters with a hodgepodge of recipes, applications, and so forth. This basic documentation requires the skills that Drupal's main contributors are already good at -- that is, understanding the code. Drupal.org could then leave the difficult task of making it understandable to the outside world to those with a different skill set. Right now, that latter group -- of which I'm a member -- is quite honestly frozen out of the community, and is then harangued for "not contributing".

To paraphrase Marx, "From all according to their abilities". Developers -- who appear to comprise the bulk of Drupal.org contributors -- are best at specifications. Writing and organizing clear end-user documentation is a very different skill set. But unlike programming, it's one that can't be quantified, which gives many developers an inflated sense of their abilities. The only litmus test is market reception... and the market is telling us that drupal.org isn't up to snuff. As I said before, I believe the solution to make it better is to stop trying to be all things to all people -- to "burn down" the parts that are failing.

I expect this comment will be as controversial as my earlier post. In particular, some will assert that I (as a writer of Drupal training materials) stand to make more money if I can get rid of drupal.org as "competition". Nonsense. Right now, drupal.org's weaknesses are making people buy my work, while at the same time discouraging some of my realcompetitors from publishing. If drupal.org takes on the focus I specify -- documentation for core and modules -- the way will be cleared for more commercial Drupal-related books, videos, and classes. That's good for all of us.

Tom Geller  *  San Francisco  *  http://www.tomgeller.com
http://www.gellerguides.com   *  http://www.savemyhomebook.com

Posted on by Omer Altay (not verified).

I feel that the problem with Acquia's documentation is the same with all documentation. I personally feel that any documentation, especially the 'how to' sections, that are over 3 pages long are too intimidating. Perhaps the documentation should be split up into two parts, one dedicated just for installing, another for upgrading and lastly one for maintenance / faqs. That way the length won't be intimidating.

My name is Omer Altay, and I'm a fan of Free MMORPG Games. I'm also a Libertarian Politically and my favorite CMS is Wordpress. Drupal is a close second. I know basic PHP, HTML and CSS. I'm here to learn more about Drupal