Posted by webchick on October 14, 2007 at 9:40pm
With the addition of the new Getting Started guide, we really ought to redesign the http://drupal.org/handbooks landing page to draw attention to it, as well as re-organize things so it's a little less intimidating. Let's brainstorm ways this can happen! What things can we do to improve this page?
Comments
Some graphics to supplement usability?
At OSCMS, sepeck and I talked a bit about the structure of the handbooks from the landing page view. Since then he's mentioned that he's been running with at least some of those ideas. The main gist I was getting at was in trying to focus the documentation according to what the question the end user is asking. (Or, to put it another way, by what kind of user the person is.) Anyway, the goal was to simplify.
I think that some simple but elegant css work, using images to enhance the various h tags could help. Is a different theme for handbook pages possible? If so, then with a nested css file we could have handbook-specific stylings that can just help the eye scan the page.
Because what I think people find challenging is that the pages are big masses of text.
Just a thought, coming in rather cold on the topic today.
Laura
pingVision, LLC
PINGV | Strategy • Design • Drupal Development
The "masses of text" is an
The "masses of text" is an important point. I find most of my handbook information via searching, never browsing from the main page (although I'm like that with most sites I've used more than once)
Stirring the pot... do we need the wall of text at all?
What if we simply listed the books along with a paragraph description of each of their contents? Maybe even with "Book covers" for each one? :)
I agree that some styling/graphics would go a long way. I'm not sure about a different theme for handbook pages, though.
...
We have five books. We have several classes of users coming to the site. Thus we have conflicts :)
For the longest time the order was a list.
About Drupal
Installing
Customization and theming
Developing Drupal
About Drupal Documentation
The books were changed to
Getting Started
Customization (vastly simplified the top level items, still working on it)
Theming
Development
About Drupal (working on collapsing some of this stuff too, needs people)
Still to do is to Break out the Development section into Developing Drupal and Drupal.org specific stuff (maintaining projects, etc). This separation will be complex so has been put off for a while.
So back to the user types.
It is hoped that Developers and themers are familiar with a mouse wheel and using a CMS so can search for documentation by mouse wheel.
That really leaves us neophytes and new comers. 'Above the fold' visibility can help these people a lot. So... For now, I've played with existing theme elements and have both 'Getting Started' and 'About Drupal' above the fold so to speak. I'd really like to draw the eye towards the 'Getting Stated' guide more so.
True about different audiences...
In fact, would it make sense to break this page down by target audience and/or desired task?
Highlight getting started at the top, since it's our "official" documentation.
Then below, have something like "I'm looking for..."
Customization help
Development resources
... etc.
In other words, rather than lumping the entire top-level tree of each book on that page, draw attention to specific sections that are useful to each target audience?
Personas
I don't think so. If there is any call to do this, I'd say this suggests our overall top-level tree is broken and needs reorganising (or sections need renaming). Which is the direction things are already moving in. And looking at your example above, it closely mimics what is there already, anyway.
Also since we are talking about the persona approach, I want to draw attention back to the document we are already working on over at http://groups.drupal.org/node/3761
This document still needs fleshing out a bit more. We still have developer and system administrator to get to first draft standard. Remember everyone, that it's a wiki ;)
-
www.alanpritt.com
Fair point...
A couple of us were talking in #drupal last night and reviewing documentation landing pages from various projects. Most incorporate our huge ungodly never-ending wall of links approach (including WordPress, interestingly), but there were a couple that were kind of interesting:
I kind of like Sun's approach and wonder if it, coupled with some schnazzy graphics/CSS tweaking like Laura suggests above, could work for our needs.
I think it would yes.
Did some browsing too and I think this is a nice example of Sun's approach with added schnazzyness:
http://developer.apple.com/leopard/devcenter/
I like this format of
- icon + title of section
- short descriptive paragraph of general contents
- 2 columns of deeplinks to popular and/or fresh content, labeld with icons to indicate topic or content-type
a mockup of the above
I think this would make a much better first impression for this landingpage.
graphics injustice
the fact that the drupal.org authenticated user is not even allowed to use the IMG tag says it all. this is a high crime for a community plumbing site.
Disagree strongly...
The amount of human brainpower and time we waste pruning spam posts from the forums and such is atrocious. I shudder to think how this would increase if we allowed everyone to post images. Not to mention security concerns with people using old crappy browsers, etc.
Any member of the documentation team can post images. It's a good incentive for people to get involved in improving documentation. :) Since the barrier to entry here is essentially, "Ask to be on the docs team", I think that this is acceptable.
But in any case, this is wildly off-topic. ;)
FWIW, IMHO, etc
1) as long as users are able to insert pages into the handbook wherever they want, i think the handbook will remain confusing. it might be useful to separate random user contributed docs into their own section or handbook, and have an 'official' drupal handbook that includes only pages that have been reviewed by editors and been positioned in the handbook precisely and have a very descriptive title.
2) i think our only hope for a truly clean and professional handbook is to find a professional editor, like the kind that edits tech manuals :) this person could lead the effort to reorganize the pages into a more traditional book layout.
if you open a good tech book (like pro drupal development), it's not hard to get a quick rundown of what's inside and quickly locate what you need. our online handbook could be the same way i think.
i think everyone would agree that we have a lot of great content, but it is so spread out that nobody can seem to find what they need. personally, i use google to do a d.o site search. i rarely browse the handbook pages.
--
Drupal tips, tricks and services
http://devbee.com/ - Effective Drupal
--
Drupal tips, tricks and services
http://devbee.net/ - Effective Drupal
...
"as long as users are able to insert pages into the handbook wherever they want, i think the handbook will remain confusing."
Agreed. However, I'm not keen on your remedy. It would segregate the wider community away from the core documentation and discourage them from getting involved. We want to be careful of this, because documentation is one of the easiest places for newcomers to get involved (from personal experience).
I also agree with about the need for a professional editor. Please find us one who is willing to volunteer lots of time ;)
-
www.alanpritt.com
1) as long as users are able
I don't agree with you a bit. You don't have to go farther than Wikipedia to see what kind of contents + organization people have been able to make. That too when people could edit it annonymously.
I also don't understand this logic that we need "clean and professional handbook". Why can't we get something that is updated regularly, even if it is little unordely? I again would like to point you to Wikipedia. It has been successful without so called "professional" help.
No only Wikipedia but other projects like Wordpress have been successful in using Wikipedia model to create documentation. Why can't we do it on Drupal?
I suggest that we open editing for Handbook to all registered users. Try it out for a week or two. You will see the proof on how much people want to help out with Documentation, but just don't want to waste time with Issue/Queue process.
All we need to do is turn on Documentation editing by all registered users and put a google custom search box next to it. It will reduce half of the beginners queries, while making a giant leap in reducing the drupa learning curve.
...
We are not going to turn on editing by all registered users again. This has FAILED in the past with to much vandalism and spam.
Anyone can add pages. For the cost of asking, you can edit most pages.
No to Google search. We eat our own stuff. I only use Drupal search on drupal.org quite successfully.
I agree with your problem statement, but not the solution
"as long as users are able to insert pages into the handbook wherever they want, i think the handbook will remain confusing."
I agree with your problem statement, but not the solution.
Having a number of Index Overseers with the ability to move content to the appropriate place would solve the problem. Unfortunately, there's currently too much ambiguity to do this without causing debates about where stuff belongs. That's why this effort of working out organization is so important.
Here's my thoughts.
[I just found this node, so I'm reposting what I sent to the documentation mailing list.]
I really think that if D6 rolls out onto drupal.org, and we have the ability to correct some of the BlueBeach theming dilemmas that pertain to the Handbooks we should definitely take the advantage.
First issue would be the amazing lack of ability to include usable screenshots of what the Handbook page is trying to demonstrate. I propose that we establish a preset size for all screenies. Something like 250 X 250 px and automatically float:right would be viewable by everyone, pertain to the paragraph of content where the image was inserted, and could even be made clickable-to-enlarge by doing a bit of theme('image') trickery. Of course, if we did this, three things would have to change; the imagecache module would be needed, the ability to auto-tag said images as 5.x||6.x, and the right sidebar would have to disappear for all handbook pages.
Let me address the right sidebar blocks now, since they are the reason we can't reliably show tables or images on our site. Those right-side blocks are necessary for the forums, imperative for the Issue Queue, and completely in the way for the Handbooks. Isn't there something we can do? Disable sidebar_right blocks for all users who are on a 'book' node? Move the user block to the left sidebar with a weigh of -10 and then disable the contributor_links block altogether? Use dvessel's floating block design for menus? There's gotta be something we can do to free us some space to begin earnestly communicating with the people who need to learn visually.
My theory on screenshots is thus. If we have a module such as Imagecache on the d.o site, we can allow handbook maintainers to upload pics of any size, and have them automatically set to one of two dimensions. A 250x250 square "thumbnail" image for inclusion directly into the text of the book page, and another image at max 640x480 (or whatever) that can be triggered into a thickbox if the reader needs to see something up close. The thumbnail sized one could be called by embedding an
tag wherever the user wanted a pic. It would be styled already, with a float:right and some margins to distance it from the surrounding text. You wouldn't even have to add a class to the image tag, since all images that appear in a Book node would have the same hunk of CSS. All of this could be handled automatically for Book Maintainers, and for logged-in contributors, the page would obviously have to go into the moderation queue if it had an image embedded in it. It wouldn't be a very large moderation queue though. How many Book contributors do we have now? Split that number by four, and that's about how many people would actually take the time to make a few nice screenshots.
Now, as to the front page redesign, I have a couple of ideas for that as well. I think it's time that our Handbooks were divided up into version-specific tabs. Sepeck has already made a huuuge leap in reorganization of the Handbooks, but there's still something lacking. The Handbook landing page is version agnostic! Whaaa?!
Let's put the power of taxonomy to work yet again. Make some tabs for every currently supported version of D, and then another tab for "Older Versions". Inside of each tab, which will be styled very 2.0 so they're huge, inviting, and friendly (think about southwest.com's anonymous user landing page) we can pull the content that's tagged for that drupal version and organize it exactly as it's set up now. "Tutorials, HowTo, and Snippets" is a prime example. Why should I have to see tutorials from D4.7 if I've just downloaded D6.0 and I'm trying to bludgeon it into submission on my very first day?
This type of approach would also assist the Handbook Maintainers greatly. Imagine if you came across a HowTo that had a code example for 5.2, and you wanted to update it for 6.x? What do you do now? You try to cram a 6.x code example either above or below the 5.x version and then explain the subtle differences between the two versions (providing you even know what they are, and few do) or you add a couple of textual lines right below the code example explaining how "we do it this way in 6.x now". Most of the readers will miss those lines, since the thing they came here for is beckoning them from between those php tags.
So what do you guys think?
Senpai
Joel Farris | my 'certified to rock' score
Transparatech
http://transparatech.com
619.717.2805
...
I've wanted the right sidebars gone for a while. It turns out it's harder then you think.
I have yet to see a maintainable 'tabs per page version' suggestion. Each assumes that the hierarchy is static. Experience shows that not to be the case. Unless you are talking about something that actually exists that I have not seen yet. I tend to strongly lean towards existing solutions that must create solutions, simple = better.
I beg to differ, the handbook landing page clearly has a Drupal 5 link in the getting started guide. :)
Past experience with trying to maintain separate trees of version specific stuff has not gone well and eventually overwhelmed people trying to maintain it. Also, something in Drupal 4.7 with a minor edit may apply to Drupal 5. So if a comment is made and later rolled into the main text, the page can be tagged with 4.7 and 5.x versions. Content that is not multiple version (i.e. 4.6 or earlier will get pruned out as not updated). If we had tutorials top level for 4.7 and 5.x then that dramatically increases the volume of information you have to process before you think you are in the right area.
The rest will have to mull over.
Style Guide and Images
We have a pretty well laid out coding standard, what's wrong with having a doc standard as well? Basically, we could create a "documentation style guide" that lays out the appropriate methods needed to lay out consistent, coherent documentation. Any documentation that does not follow these methods, will be flagged as "buggy". This way, users can still contribute docs, and participation is still encouraged, just in a structured way.
Also, I highly support the notion that images help. Hypothetically speaking, lets say the landing page has a "installation" section and a "troubleshooting" section. As text links, those two word are only three letters apart, and require the user to look at each one individually, then make their selection. Now, on the flip side, you keep the text, but place it in some iconic imagery: maybe an icon of a gear for installation and an icon of a red cross for troubleshooting. The first time a user visits the site, they still have to look at each icon. But now, the user only has to scan the page to find the appropriate section each subsequent time they visit the handbook, because of the visual association they can make with the two separate images.
here you go on the style guide
http://drupal.org/about/authoring
Boy, that's embarrassing.
Boy, that's embarrassing. That's what I get for opening my mouth without looking. How about a documentation template? Something that gets you started, instead of just a blank textarea.
Fieldthief Module is good for this
We actually do this on Openplanner.org using the Fieldthief module. Users create planning templates and use them to create a new node based on that template. We could create a content type called a 'template' and use the Fieldthief module (which actually needs a patch to allow it to handle the body element of a node form) to populate the body of the new documentation node.
versions
I think it would be a good thing to make clearer what handbook pages are useful for what version of drupal... this is very confusing and frustrating. especially if you're new on the page.
maybe a filter, like in the modules section. or different root chapters could be the way for this...
...
Most contributed pages are now tagged with version applicable links. It may be that the tags need to be highlighted/themed better or the pages pruned.
Task-oriented navigation
I was looking through my virtual attic of old and discarded stuff, and stumbled over a never-submitted forum post which I wrote back when I was working on my first Drupal site. Rereading it now, it makes as much sense as it did then, and this looks like the perfect place to post it:
So, is something like this possible? I'm not suggesting to replace the current landing page, but I do think an alternative landing page with task-oriented navigation would be very helpful.
--
Hilde Austlid, Drupalchick
Another issue
There is a related issue in the docs queue for organizing things by the type of user and common tasks they must do: http://drupal.org/node/114078. That issue was about reorganizing entirely (and the separate issue of multiple parent pages is altogether different and not possible now or in D6) and not using taxonomy but I wanted to point it out as a discussion already started in that vein.
Using taxonomy for this is interesting. The biggest problem is how do you return those taxonomy results in any kind of order or context that makes sense? Once you pull on taxo you are losing the book structure and just have a river of nodes all marked with the same thing. This is the problem we have with the current version taxo tags. If you click on a Drupal 5 tag you get back a mess of stuff that is pretty much useless.
Learn Drupal online at Drupalize.me
A rough idea
OK, so I can't sleep and I was thinking about this some more. For now I am just focusing on the weird "middle" section we have on Customization which is I think the prime place for many "regular" users of Drupal. Here is a way of looking at that section that may make more sense. The names of the sections are not spot on yet but can be sorted out, the real question is does the basic idea here seem worth pursuing? If so, then we can squabble for a month over the names, order and specific elements. ;-)
The How Do I...? handbook
Drupal Cookbook
Contributed Module handbooks [The module handbook section is where everything specific to a module goes, including tutorials, howtos, snippets and API info.]
Recipes [This is for multiple module howtos]
Customize...[These sections have all tuts, howtos, snippets, etc for the topic covered.]
- Blocks
- Nodes
- Pages
- Forms (things like login and search)
- Forums
- Profiles
- Navigation
- Other stuff, etc.
Technology Stack [This is for all that "not really Drupal" techy background stuff]
- OS
- Web Servers
- DB
- PHP (settings, not snippets)
Videos and Slides
Learn Drupal online at Drupalize.me
Hmm... Perhaps two new vocabularies?
Good question. Thinking aloud here: Two vocabularies, one for task, and one for implementation method/handbook section? Using views (if that's realistic to use at drupal.org?) to show the handboook links. So someone looking for information about navigation would get something like this:
The table should have a column for Drupal version as well -- it's omitted because of laziness ;-)
--
Hilde Austlid, Drupalchick
The docs really needs improvement
Hey people,
The documentation really needs to be improved. As a new drupaller, when I got the handbook, I don't knew where to go. The main problem isn't quantity, it's organization, it's IA. Some features like the lack of screenshots can be a wall to the new developer to understand the concepts of Drupal. Then I started to research some docs, I found the IBM tutorial (but it's in Drupal 4.7) and a few other good blog postings (like Lullabot ones), finally I bought the Pro Drupal Dev book.
Documentation is a very important point to get a successfull project. Others projects like symfony framework have a really good documentation.
Well, that's my point, I will try to contribute as much I can!
more specific
There are over 1400 pages and 5 books that comprise the handbooks.
Lack of screen shots where? The getting started guide for Drupal 5 has lots of screen shots. Please be more specific. Also, what type of documentation. We have beginner docs, various how to, theme and developer docs.
Similar concept as joroy
Graphics help a lot. The buttons proposed are bogus and do not fit, but the categories are a proposal.
http://www.drupalcenter.de/files/duku-kategorien.jpg
For those not common with german... Einsteiger ="Beginner" Fortgeschrittene="Intermediate" Designer="Designers" ;) Entwickler ="Developer"
I thought of a landing page that gives this subdivision. It would not keep it from also giving an advanced search field, so you could filter/search for all Handbook pages concernig cck that are on Beginners level of knowledge.
When I look at zirvaps post and the handbook page about nice menus, it comes to me, that the project page of modules would win a lot if they had some screenshots of the basic principles of a module.
Life is a process
Life is a journey, not a destination
Restructuring proposal
I was pointed to this thread from the documentation mailing list where I had enquired about the possibility of restructuring Drupal docs according to standard software industry practice. I see WebChick in her message above (October 17) has already suggested the same approach and I'd like to second this idea (in the strongest possible terms) and expand on it.
I should mention that I'm a technical editor by trade and have worked on a number of early-stage commercial software development projects. One thing these projects tend to have in common, is that the first documentation is written by developers and usually reflects an inward focus. It's almost always biased towards describing the UI and the program functionality and the content is generally divided in a way that makes perfect sense to people on the inside, but seems arbitrary and annoying to newcomers. As the project matures, there is usually a realization that the documentation should not really be "about the product" at all, it's about the users. I know it sounds kind of strange, but it's true. The (non-developer) docs only have one purpose: show the users and sysadmins how to do the tasks that they want to do.
Drupal documentation is definitely in that early, inward-looking stage. This isn't a criticism. It's a natural and healthy part of the growth of the project. However, sooner or later the information architecture must be updated so that it looks outward to the various users and to the tasks that they need to achieve.
As WebChick pointed out, the way to do that is by dividing the books by audience and then put chunks of task-oriented information into closely-related groups. I would think that Drupal has probably four or five logical "books"
Installation Guide (could plausibly be an "installing and upgrading" guide): Should be a very lean document that describes little more than the system requirements and the basic core installation.
Administration Guide. The audience is strictly system administrators. A typical sysadmin runs a variety of servers, sometimes multiple CMSs, mail servers, application servers, databases etc. They will expect to see instructions for managing users, configuring multiple sites, backing up and restoring content, integrating Drupal with the environment, managing security, optimizing performance, maintaining logs. Most of their other applications and servers will have documentation that covers the same subject areas and it would be helpful if Drupal docs followed the same model.
I should point out here that even though Drupal has a whole UI area called "Administration", many of the tasks you can do in the "Administration" area, should not be covered in the Administration Guide. The Site Builder Guide or Site Customization Guide (I'm not sure what you'd want to call it) would cover this stuff. This would include creating content types, developing communities, customizing the appearance of Drupal, displaying content, laying out pages, configuring menus, developing taxonomies. Note that I've presented these as generic topics, not using jargon like "Creating Blocks" which would get back to that inward looking approach I mentioned earlier.
Apparently there is a belief that documentation of core modules should be kept separate from the documentation of contributed modules. However, if documentation is truly about the users (and not the product) this approach is not helpful. Really the only organizational principle is whether or not you are helping the user accomplish their objectives. Pulling apart closely related material because insiders perceive some kind of distinction will make the reader feel that the documentation is arbitrary and unhelpful.
Finally there is the developer documentation. Typically you'd see a Developer Guide which would have lots of conceptual information illustrated with lots of code samples and snippets and an API Reference.
I'm thinking of logging this proposal as an issue, but I wanted to raise it here with the hope that others could clarify my thinking (I'm a relative newcomer to Drupal). Sorry about the lengthy post.
...
I am currently overwhelmed with work so can't respond point by point but will address what I can briefly
Having spent the last two years with a remarkable lack of contributed module documentation being maintained/updated/exist at all, I cannot in good faith commit long term any farce of a guarantee towards maintaining it as part of the 'core' documentation. That is the primary reason why core is separate from contributed modules docs. In tutorials, how to, etc, mix and match to a persons content. For core documentation that is upgraded per release, there needs to be an identified base documentation that we will attempt to ensure is updated. There are hundreds of contributed modules with many beginning life, dying out, forking at any given time. I haven't been able to track all the contributed modules and their use since 4.7.
This is not an 'insider/outsider' us vs. them issue, this is a reality of contributed work effort, best intentions and vapor ware documentation.
The API guide is referenced at the very top of the /handbooks page already. I intend to re-do the /handbooks page as soon as an article gets a technical review that may address some of your other concerns. The developer guide has grown somewhat organically and needs a hatchet edit in the near future in any case.
The re-organized Getting Started guide was absolutely about helping the user and I fail to see how it doesn't. It closely matches your requirements for an 'Installation Guide' in any case. If people will actually write content for an 'Administrative Guide' then I am willing to separate out sections. As to a 'Site Builder' section .... We've tried to get content for such a section before. Doesn't seem to happen so until people do so, we have collapsed it all under the Site Customization' section as a bucket for these various types of articles. I am perfectly willing to rename 'Tutorial' How To, Video etc to whatever, but we cannot arrange content that does not get written.
Docs and Landing Page tools
I'm a Drupal newb, but I was inspired by two brief conversations I had at the doc sprint at Drupalcon Boston: one with Addi and one with Steven.
In order to provide everyone with both a working example of how the Documentation section might be better structured and an example of a more-usable "landing page", I've created a one-page dynamic (javascript/HTML) outline of pretty much all of the Documentation at drupal.org.
Every leaf in the outline links to a specific page of documentation at drupal.org, and all branches of the outline tree can be expanded or collapsed at will.
Please keep in mind that this is not necessarily an outline of how the Documentation is currently organized, but rather just my opinion of how it might be better organized. The nifty thing about it is that you can use it right now and you can edit it right now.
My hope is that this will give us all a common tool with which to quickly share and test-out each other's ideas about how Documentation might be better organized.
Have a look in the Documentation Forum for more info:
Drupal Project - Knowledge GUI (Beta)
http://drupal.org/node/233601