GHOP #38: Improve documentation for the imagecache module.

Claimed by alexandrebfarias. Don't know drupal.org username.

This is my Drupal username BTW.

@etinin, feel free to ask me anything you need to know. You can catch me via my contact form or irc.
I would personally like to see this module better documented. I've failed in most cases to explain how it works, to the point that I've given up trying.

I've attached my work, is there anything else I should add?

The file only contains <img> tags, I didn't break lines with
as I think that's not necessary for Drupal.

Rock! This is great stuff Etinin. I've got a few tweakish things:

1. I would mention up in the first paragraph that you can use imagecache with any images uploaded to Drupal, so you can use it with Image module as well as normally uploaded images using the Upload module but the most common way to use it is with CCK and Imagefield.

2. I would move the sentence about needing CCK and Imagefield down to when you start the demonstration itself. You should mention all of the prerequisites, so it assumes you have already installed and enabled imagecache, CCK and imagefield, as well as also having already added an imagefield to a content type.

3. You should probably tell them to click the Update preset button after each step (select action and fill in dimensions) just to be sure they don't get lost.

4. With the content type section at "To accomplish that, first go to Administer>Content Management." I would then add, "click the configure link for the content type with you imagefield" or something like that to get them from the content type listing to the screen with Display fields on it.

5. On the final results screenshots I would add a little title to each pic so they know which one is the teaser view and which is the full.

6. The last thing I'd do, is for the theme function bit at least have a bullet list explaining what each of the parameters is. e.g.

print theme('imagecache', $ruleset_namespace, $image['filepath'], $alt, $title, $attributes);

• $ruleset_namespace is the imagecache preset name
• $image['filepath'] ... (this one you probably need to help folks out with maybe how that can find out what the filepath is)
• etc...

All in all this is already going to be a great help to a LOT of people.

This looks great! Technically a-okay, no problems that I noticed on a read-through.

add1sun most of the issues I found also. In addition:

In addition to telling users when to click "Update preset", also be sure to mention clicking "Create preset" after filling in a label. Which buttons to push seem to throw a lot of people off (part of the UI's fault admittedly). Be sure to include the "Update preset" button in your screenshot also.

A small nit-pick that the path definition should be consistent, Administer>Content Management should be Administer -> Content Management like the example earlier in the file.

Thank you Etinin!

Hi, thanks for the feedback. I've done the changes as requested.

Absolutely fantastic! One last tiny detail: let's use $preset in the example rather than $ruleset_namespace "ruleset" isn't part of the imagecache vocabulary and we'll probably phase out "Namespace" from the interface anyway. Preset is the word we'll be using in the future. Thanks!

Add1sun, can we get this added as a handbook page? (I'm intentionally not on the docs team).

Well webchick quickly solved my lack of documentation-team membership. ;)

I updated the existing imagecache docs page at http://drupal.org/node/163561, this is 20x better than what we had. I also update the project page with the documentation link, as it's definitely going to help a lot. Thanks again!

Garsh... and now I'm getting close to releasing 2.x, with a brand new UI :), and additional installation requirements... Caffiene and I are a bad combination.

You work is awesome I really appreciate it... I'll use it as a model for building the docs for the 2.x release...

We can make another task for making a new 2.x documentation page then :D