The current Drupal documentation page has two major flaws: its hierarchy and the choice of information to present. Currently, the site is unclear, redundant, and intimidating. It is at once extremely general and overly detailed.

Prime examples of this are:

*"Projects and Features" is listed under the "Getting Started" section. Is this also not applicable to "About Drupal?"
*It is not immediately clear to new users what the difference between a tutorial, snippet, and HowTo is.

It seems that with all of the constant influx of content, the Drupal community has a difficult time centralizing, proofing, and prioritizing contributions while maintaining the sponetaneity and openness of a community plumbing format. Thus, I think the Drupal community should consider a complete revamp of the documentation page. There are three parts to this.

First, don't make the page handbook-centric. While it is a novel idea to quantify user submissions into such manageable units, it leaves the documentation page too decentalized and overwhelming to newcomers.

Second, and most importantly, have an official, community-collaborated Fairly Exhaustive Drupal Guide for every major release. This should cover everything-- from background behind the project, to the technology stack, to an installation walkthrough, to an explanation of core modules and Drupal's taxonomy system, to theming, to hacking modules, etc. Essentially, centralize the documentation page by organizing all pertinent current contributions into one peer-edited coherent ebook. The closest two things I could find to this on the documentation page were:

http://drupal.org/getting-started/5
http://drupal.org/handbook/customization/tutorials/beginners-cookbook

The first is already a big step towards such an exhaustive guide. Why not finish the job?

The attached image is a rough mock-up of what such a documentation page could look like.

And finally, make "About" a separate section on the Drupal webpage. "Documentation" is a hiedous word, and a huge turnoff to someone looking to quickly grasp what Drupal is.

Regarding motivation and manpower: Google has a summer of code... there could be a Drupal Documentation Day where the community- and not just those working on documentation issues- takes a step back and lines up for a small topic to tackle.

It is critical for those translating Drupal documentation to other languages to have an exhaustive, centralized, open document (that is prominently displayed on the documentation page). Only with such a document can translators help bring the greatness of Drupal to a new population of developers. Without such a document, it becomes difficult to convince those interested in Drupal that it is well documented even in English.

CommentFileSizeAuthor
newdocpage.png169.38 KBholland1945

Comments

add1sun’s picture

add1sun commented

Hi holland1945,

Thanks for sitting down and looking at this. I think we all agree that docs need work. You'll find there are a number of issues and discussions that address this from different angles (e.g. http://drupal.org/node/199388 and http://drupal.org/node/233601) and there is also the overall drupal.org redesign project as well.

The getting started guide was indeed a great first step to pulling things together and hopefully we can add that code to CVS so more people can help with it. I think sepeck's original plan was to move on to other topics in the same format so that instead of one massive guide, there would be a few guides broken into the big topics and people could work their way through successively as needed. And, yes it is to be versioned with each version of Drupal. The idea of translation is definitely one of the goals with that effort - we're still getting there.

One issue we have with the "create the one almighty, versioned, PDF book" is that right now it is a very manual process. The getting started guide is in docbook format, which then needs to be exported as HTML pages to be copied into the handbook and then also exported as a PDF. Every time it gets edited these steps need to be done again. Yes, there are more automated ways to do all that but we need determine what the best technical way to do that would be that fits within the drupal.org infrastructure and then get it done. It is a bit more of task that it may sound like at first blush. In terms of "Why not finish the job?", because it is a TON of work and getting to where we are now has been quite an effort. I think we would all like to get the handbooks into a well-oiled machine and are moving in that direction, but we are still figuring out what to do with a lot of the grit and grime, which has great stuff in it. I know that you do not mean offense by asking the question, but it does sound a bit like "no one is doing anything and why not?"

In addition to some of the technical considerations, we need to be very careful about what goes into "the book" since that will not be editable online in our current wiki style. The barrier to entry for editing anything that we put out as a versioned, PDF'd book will be quite a bit higher than the regular community contributed documentation. Ideas about what specific items you feel should be in the versioned book would be welcome and is probably a good place to start in terms of figuring out what needs to be done.

Re: the word Documentation, it was recently changed to that from Handbook because of a hue and cry that Handbook was horrible and the word should always be Documentation, so everyone has their own opinion.

We did have a docs sprint the day after DrupalCon in Boston, just 2 weeks ago and we got quite a bit of work done cleaning up the issue queue and hashing out some new ideas. We are currently looking at having online meetings once a month on IRC (in #drupal-docs) to hash out bigger issues (like this one) in real time. Hopefully we can keep and increase the momentum we gained at DrupalCon. I know that one big push for the coming year in the Drupal community is to have more sprints for various topics (mostly code/architecture) but there I definitely see us (me at least :)) trying to pull together some docs sprints throughout the year as well.

Again, thanks for posting about this and I welcome the opportunity to work with you on making the docs rock.

add1sun’s picture

add1sun commented

holland1945, looks like sepck went forward with the plan he talked about at DrupalCon. Does the new landing page layout satisfy what you main concern in this issue was?

sepeck’s picture

sepeck commented

the new landing page is an interim step on the sorting of the content.

holland1945’s picture

holland1945 commented

You guys have been overwhelmingly responsive to my post... it really says a lot about how welcoming the Drupal community is to feedback from new community members.

The new landing page is indeed a huge step forward. Seems like I joined the discussion a little on the late side...

Unfortunately there's very little I have to offer in terms of solving the technical issues of updating the "getting started" pdf directly. I'm going to take a step back, process all of this, and figure out what the next best way to contribute is. That may very well be just focusing on translation work, and supplementing any document we produce with most-requested materials to create our own beefier pdf.

But yeah the re-haul really dashes many of the original criticisms I had.

Some minor issues:

I do wonder if there may be a more graceful way to introduce theming. First, in the "introduction to theming" page at http://drupal.org/node/221881, it might be really helpful to immediately link to w3schools alongside mention of XHTML, PHP, and CSS and explain how invaluable they are. Similarly, the new drupal 6 theming module and firebug could be mentioned as well. All of these are great resources to keep in mind when approaching Drupal theming, and its good to get them right out there in the beginning. On the second page, "theming overview", the first two paragraphs are dense and would probably be a turnoff to most designers. Perhaps first start with a very general, non-technical description of theming starting with the concept of Drupal pages being XHTML skeletons with dynamic content plugged into them through Drupals various function calls. Then go on to describe that different themes are basically different takes on that skeleton and their accompanying style sheets, and are themselves built on a theming engine, which itself is built on top of the Drupal core. Once that's said, a deeper exploration of theming nuances can begin in full force. As it stands, it's very useful and informative information, but seems to be too intense and premature.

The troubleshooting faq underneath the getting started section might be better placed in the "beyond the basics" section, it seems a little out of place to put it in a section with content aimed at those trying to learn more about Drupal.

There could also be a small text description next to the "Drupal 5 pdf" to explain how it's different from the "getting started" link. likewise, a description alongside "getting started" - though certainly not necessary - will help users better understand whether the information they need will be there or in the pdf. Users shouldn't have to click-in to find out whether or not what they are looking for is there.

I don't particularly like the layout with the theming guides and beyond the basics on the right, and think they might all be better off aligned left and re-ordered. Lastly, the Drupal Resources link on the word "this book" leads to an About page. I think it might be better for much of that information to be merged with http://drupal.org/getting-started. A resources page should probably link to forums, guides on how to use the forums, drupal dojo-like resources, basically, areas or sites devoted to helping the community or guides on getting help, as opposed to concrete pieces of content which are best left to the "Beyond the Basics" section.

I hope this was useful! Would love to hear what you all think. I'm really looking forward to how things continue to improve.

Oh yeah, when are these IRC meetings going to be scheduled?

sepeck’s picture

sepeck commented

Individual improvements on the theme guide can be made with appropriate edits/updates on that page/section itself in collaboration with dvessel who wrote/created most of that section (D6).

The Troubleshooting FAQ will have it's own little section at some point. It's sort of hanging out there for the interim till it goes to it's own home. It's evolved in terms of content.

The last book (About) is being substantially changed in focus and nature in the near future and substantially shredded and split. Part of it is already going in the direction you mention. All the case studies and marketing stuff will be it's own little home and I am creating a top level press page intro to it for the news agencies to have a nice little link fest and intro text to information (history, logo, stuff). Then the marketing folks can do or ignore the rest of the section as they choose.

sepeck’s picture

sepeck commented

I should also note that much of this has been planned for the last two months :)

holland1945’s picture

holland1945 commented

Great, can't wait to see how things develop. Sorry to have forced so many of you into providing what essentially seems like a status update on something that has been in the works for quite a while now.

sepeck’s picture

sepeck commented

bah, status update good for people periodically. :)

add1sun’s picture

add1sun commented

Don't apologize. None of this stuff was written down anywhere that someone could find it so, if anything, we should apologize for not broadcasting plans. Hopefully more active use of the mailing list will encourage sharing of the "bigger plans" in the pipeline.

add1sun’s picture

add1sun commented
Status: Active » Fixed

I'm going to mark this fixed since the main thrust of this is addressed with recent changes.

Anonymous’s picture

Anonymous (not verified) commented
Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for two weeks with no activity.