[documentation] Proposal for a "Contributing to Drupal" handbook section

[Joel Farris]

I've been toying with an idea for attempting to teach the same process  
to both a newbie and a seasoned vet on the same page without either  
one of them getting lost or confused. I have seen this approach  
deployed very successfully on a certain hosting company's help pages,  
and it gave me the following idea. It's a daunting thought, to be  
sure, but one that I think we could accomplish with every new Book  
page if we all began to follow the formula of Brief Overview, followed  
by Detailed Analysis. Let me explain. No, there is too much. Let me  
sum up:

<h1>Contributing back to Drupal</h1> [This is the main tab called  
'Contribute']

   <h2>Using the Issue Queue</h2>

     <h3>Quick Info</h3>
       * The Issue Queue is our bug tracking and ticketing system, and  
is located
         at http://drupal.org/project/issues.
       * Create Issues using http://drupal.org/node/add/project-issue,
         but only after you've <a>thoroughly searched</a> for three  
words related
         to your problem, and you're sure there's no currently active  
issue(s).
         To create a new Issue, use the following guidelines.
       * Select the most appropriate Project. There are five main  
sections:
         -- Drupal Project [The drupal core itself]
         -- Installation Profiles [The instructions that create a pre- 
built site]
         -- Modules [Contrib modules contain additional site  
functionality]
         -- Theme Engines [The glue between PHP code and the resulting  
HTML]
         -- Themes [Templates that make up the design of a site]
       * Select the appropriate Component. This is often the hardest  
thing to
         classify, but it will help your new issue obtain the most  
attention.
       * Select the Category:
         -- Bug Report [Used to report a problem, error, or omission]
         -- Task [Something that needs doing, and has a definitive  
guideline]
         -- Feature Request [What could Drupal or the contribs do  
differently?]
         -- Support Request [I can't make this module,theme work like  
it should]
       * Select a Priority:
         -- Minor [Should be done, but hey, whenever is fine]
         -- Normal [This needs to be fixed, and soon]
         -- Critical [The earth will cease rotation if this isn't  
addressed]
       * Select an Assignment (optional):
         -- Unassigned [Anyone can handle this. In other words,  
unclaimed]
         -- Your UserName (In effect, saying, 'I'll handle this one')
       * Select a Status:
         -- Active [This is an active issue that has not been resolved]
         -- Active (needs more info. [No patch can be created until we  
hash out
                   some more details])
         -- Patch (code needs review) [This attached patch needs peer  
review]
         -- Patch (code needs work) [A patch is attached, but it sorta  
sucks]
         -- Patch (reviewed and tested) [Can be safely committed to  
the Project]
         -- Patch (to be ported) [Also needs to be ported to another  
version]
         -- Fixed [This means the issue has been satisfactorily  
resolved]
         -- Duplicate [There's a previous issue that addresses this  
problem]
         -- Postponed [Must wait on some other issue(s) before  
proceeding]
         -- Won't Fix [The project maintainer has decided not to  
pursue this]
         -- By Design [This is not a bug. It's user error/ 
misunderstanding]
         -- Closed [DO NOT mark an issue as closed. Use 'fixed'  
instead. Cron
                   will automatically close the issue after two weeks]

     <h3><a>Detailed Instructions</a></h3>
       <div class="collapsed_by_jquery">
       The Issue Queue is used by the community to track problems and  
solutions
         for every Project hosted by drupal.org. Each contrib module,  
theme,
         translation or install profile available on drupal.org is  
called a
         Project, and they each have their own Issue Queue. We call it  
an
         Queue, but you can think of it as our bug tracker or  
ticketing system if
         you'd like. Just be sure to use the appropriate Queue for the  
Project.
       Don't report a module or theming problem in the forums because  
the
         project's owner won't see it. Instead, use the Issue Queue.
       When selecting a Priority for your new issue, make the right  
choice. This
         selection is important, because it will affect the speed at  
which your
         Issue receives attention, but has the inverse effect of  
bringing scorn
         upon your head should you artificially inflate the need of  
your ticket.
       </div>

<h2>The next main subsection...</h2>

And so on, and so on. We need to explain how to file documentation  
issues, module issues, theming issues, and translation issues  
separately if the drop-down details are slightly different. I know for  
a fact that lots of people get tripped up when trying to create a docs  
issue, because they're not sure about the Category drop-down.

What do you guys think about an instructional style like this? Would  
it work for our top level landing pages? I know it's not going to fly  
for all the detailed HowTo pages and stuff like that, but if I'm  
coming to the CVS section to reference a specific command, I'd want it  
on the top in a bulleted-list style. Maybe even with icons?

Same thing goes for a one month old beginner who's coming back to the  
CVS page(s) to copy/paste these commands. If I'm a one day old newb,  
however, I have all the detailed text available to me on the very same  
page, and all I have to do is either scroll past the Quick Info div,  
or click on a 'jump to the detailed instructions' link.

I think I like this idea a lot, now that I've written it out. If  
nobody objects, I will begin converting all our top level landing  
pages to this format.
-- 
Joel Farris
"Protection and captivity so often look the same."
   ** Robert Ludlum



> On Mar 8, 2008, at 5:03 PM, Addison Berry wrote:
>
> Basically the idea is to really make a contributing guide that will  
> walk a newbie through every single step if they want it (and I find  
> more and more people do want that) but let bolder people jump to  
> what they need.  I think we still need plenty of playing around with  
> the exact organization and naming of things and I don't expect the  
> finished product to look like what we have right now. If folks have  
> ideas for totally new ways to organize the info we are targeting  
> here, please feel free to propose your outline over the next week or  
> so and we can really hash it out...
>