Acquia Documentation Survey - Results - The Way Forward
Posted on Sun, Jun 07, 2009
by Jeffrey McGuire
by Jeffrey McGuire
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?
- 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.
- 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.
- The (large) majority consider module and core documentation unimportant.
- 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.
- 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.
- A distant 3rd: offline HTML/helper apps
"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
"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.
Sign up for our blog newsletter!