[documentation] [Documentation feature] Request for comments - confusing term use in titles

[sepeck]

Issue status update for 
http://drupal.org/node/112923
Post a follow up: 
http://drupal.org/project/comments/add/112923

 Project:      Documentation
 Version:      <none>
 Component:    Misc
 Category:     feature requests
 Priority:     normal
 Assigned to:  karldied
 Reported by:  karldied
 Updated by:   sepeck
 Status:       active

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.




sepeck



Previous comments:
------------------------------------------------------------------------

Fri, 26 Jan 2007 05:35:45 +0000 : karldied

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




------------------------------------------------------------------------

Mon, 29 Jan 2007 05:57:39 +0000 : karldied

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




------------------------------------------------------------------------

Mon, 29 Jan 2007 06:57:50 +0000 : Senpai

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?