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

[karldied]

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:   karldied
-Status:       active (needs more info)
+Status:       active

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




karldied



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