Forum post: "Terms like snippets, recipes, HOWTO, how-to, mini-modules, and tutorials are thrown around here and there. Organizing these pages and calling them one thing, tutorials for example, would make it much easier to find the steps to solve a problem."

How to title pages is covered a little in the style guide, http://drupal.org/node/22299 The above post illustrates that the distinction between some terms is not uniform or clear.

* What distinguishes a tutorial from a HOWTO?

* What distinguishes a site recipe? Are there other kinds of recipes, or are they then called HOWTOs?

* For what is "mini-module" applied? When does a snippet become a mini-module?

Here is my stab at a working definition for "Snippets" and thoughts on what might be defining characteristics for the terms. Please add your two cents.

HOWTO: A step-by-step list of directions to _______ (accomplish what kind of task?).
* detailed
*

Mini-module:
* See node/70903 which is in PHP and Javascript snippets
* (I'd discourage this term...)

Site recipe:
* Encompasses multiple modules (?)
* "How I achieved my setup" stories (?)

Snippet: A snippet is a small piece of specific code that can be added to a theme template file or used in a particular module (a hack) to provide some functionality.
* small
* code
* designed for insertion into template file or module

Tutorial:
* broad (?)
* example-based; shows one way, not necessarily every way
* not a comprehensive reference

Comments

karldied’s picture

karldied commented
Status: Postponed (maintainer needs more info) » Active

Status "active - needs more info" is not mailed out to list. Updated.

senpai’s picture

senpai commented

I'd like to get some sort of standard naming for a HOWTO as well, since I'm about to propose an entire section on "How Do I accomplish X task?".

We could call it a HOWTO section, a How Do I section, or even a Beginner's Steps. I lean toward a "HowTo" naming convention, because it'd look good as a primary link.

When I figure out how best to go about crafting a series of How To's for Beginners, and how this series should best integrate into the existing d.o structure, I'll be writing my little ass off to begin helping out those newbs who need a bit of handholding throught non-obvious parts of their new Drupal site.

I already have my first article underway. "How Do I install TinyMCE so that it works". I've answered this question three times in IRC just this week. If I had a hard time with it, and three others did too, there needs to be a step-by-step instruction set for v5.x users.

Can we agree on a HowTo section for the site? Thoughts?

sepeck’s picture

sepeck commented

go here: http://drupal.org/handbook/customization

Wait until you are ready to submit your first how to, then
Click the Add a child page button and add a page titled 'How to ...' or similar.
Add your how to's underneath.
I will alias the top level when I see it.

Assuming it works out over time, we may be able to refine and move some existing content over as well.

senpai’s picture

senpai commented
Status: Active » Fixed

This issue has been fully addressed with the new Handbook re-org. And yeah. Mini-module, as a term, should be abolished. Denied. Removed to the South Pole. Or the North Pole, if that's further from *you*.

Anonymous’s picture

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

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