Documentation case studies
The following pages are my attempt at “pretending” to be a Drupal newbie, and seeking out answers to common questions on Drupal.org. The tests will obviously be a bit biased, since I am “not” a Drupal newbie. But I’m pretty good at putting myself into the shoes of a beginner and envisioning what they will encounter and how they might react.
The purpose is to identify weaknesses in the Documentation (both regarding content and information architecture) and figure out how to improve on them.
How do I add images to my Drupal site?
User information
A new Drupal user, who has just recently installed Drupal 6. No knowledge or understanding about how Drupal works is assumed. I installed Drupal 6 because, of course, it’s the newest version, and I don’t know that “contributed modules” might not yet be available for it. I may have some prior experience with other content management systems, which might affect my assumptions about how Drupal works. My computer skill level is at least intermediate.
Goal
To find out how to add images to my new Drupal site.
Steps Taken
- Tried using the search form: “add images to Drupal”. I clicked some of the results, but they are all people asking the same question as me, many with no reply, or else displaying dizzyingly complicated PHP code. Tried the following searches as well, with no better results: adding images to drupal, images in drupal, including images, how to add images. I’ve now given up on the Search feature. (note: a search for just “images” was the only useful search, leading only to Image module, but this user didn’t use that search).
- Clicked the main Documentation tab.
- First tried Getting Started and found nothing after several minutes.
- Moved on to Beyond the Basics.
- After about 5 minutes of clicking many many links and finding very little (e.g. I found HowTo > Node Listings with Thumbnails using Drupal 5.1, CCK and ImageCache … but this is way over my head, and anyways it says Drupal 5.1), I finally came across Beyond the Basics > Contributed modules > Asset and media management modules (http://drupal.org/node/206708). This page is a “start” but still not what I was looking for, and I was lucky to even find it in the place it’s categorized (since I’m a newbie, I don’t know what a Contributed module is… I’m looking for how to add images - I don’t even know yet that I’m going to have to install a “contributed module” to do this). But I’ve found this page now, so let’s see if it helps. I’m a newbie and the word “Asset” doesn’t mean anything to me (and “Media” sounds like audio/video to me), but I happened to notice a few instances of the word “Image” in the listing of sub pages, so I think this might be worth looking into.
- Clicked on “Asset Manager” since it’s first. Hmm doesn’t make a lot of sense to me. A comment below on the page says it doesn’t work, so I’m moving on.
- Clicked on the next link, “Asset: Unify asset file management”. The screenshots are a welcome surprise, though I’m not sure what they mean. I don’t see any mention of images though, so this couldn’t be what I’m looking for. Moving on.
- Clicked on “Embedded Media Field: Third Party Videos, Audio & Images”. This looks pretty scary to me. It mentions terms like fields for nodes, CCK, %YourType%, and I’ve also noticed the version info at the top right. I’m using Drupal 6, so I must be in the wrong place. Ah now I see this is for embedding images from “other” sites. Moving on.
- Clicked “Gallery: Embed Gallery2 in your Drupal site”. Galleries have images, so maybe… nope this won’t work. It wants me to install some other software besides Drupal.
- Clicked “Image painter”. Woah! Scary. Moving on.
- Clicked “Image: image nodes, attached images, and galleries”. Ahhh now this is looking more promising. I don’t know what “Each image is stored as a node” means, but I’ll keep reading. I’ve now read this page, and this looks like the way to go. But I see a few “more” mentions of images in the menu and have started to grasp at this point that there are a variety of possible ways to do this. I bookmark this page, and decide to have a peek at the other image links just in case.
- I click “IMCE: Image uploader and browser”. Uh oh. This looks promising too. Now I’m not sure what to choose. I click the link to view the IMCE 6 Demos. I click the “Image” icon, but at first can’t figure out how to do anything here that has to do with images. Ah there’s a little weird icon next to Browse. And there it is, IMCE. Not bad. I decide to click back and watch the screencast to learn more about this. Oops, the link to the screencast is broken.
- I take a quick peek at the menu to see it there are yet more image modules I need to look at. I see “Img package: Easy way to display images in posts & comments”. Nice! It says it will be easy - I click the link. I read a good bit of info on this page and decide to click on the link to the Img Package project at the top. What?! This module has been “abandoned”? Why didn’t you tell me that before while I was reading all that stuff on the previous pages?
- I take a last glance at the menu and see no further mention of “Images”. So this must be all there is. (of course I will hear about a variety of other image modules later that weren’t listed here and be confused at why I hadn’t known about them earlier).
Post test notes
- The results of the test were not promising. I had a particular page in mind that I’ve read in the past, which compared a number of the image module options, and was unable to find it despite my own best efforts. If I couldn’t find it, even knowing it was there somewhere, a newbie would only find it by sheer random luck.
- The page I did find the most information on was not ideal. It was cluttered with a mixture of different media-related modules, some of which have become abandoned or outdated, and definitely did not represent most of the available options (all would be difficult of course, as it changes so rapidly). In particular there is no mention easily found regarding Imagefield and Imagecache.
- The page I found also required me to muddle through documentation of varying quality on each possible module, trying to decipher the merits of each to see if they meet the needs of my site. There was no concise all-in-one place overview of what options I had to choose from - I had to read through overwhelming reams of information about a variety of modules, almost blindly sifting for key info to help me decide if the module would suit my needs (this might be ok when it comes to more advanced or specialized modules down the line for the user, but this is “images”, and likely one of the very first things a newbie is going to look for).
- Drupal.org’s search feature was almost completely useless in this case. It found almost no relevant results for just about every query I could think of (or at least a newbie is likely to think of).