[documentation] Proposal for a "Contributing to Drupal" handbooksection

Sat Mar 8 01:45:42 UTC 2008

This looks great to me.  I'd love to help.  Got inspired by Addi's session
at Drupalcon (couldn't stay for Code Sprint).

Also, "Contributing To Drupal" seems OK to me.  

Rick

-----Original Message-----
From: documentation-bounces at drupal.org
[mailto:documentation-bounces at drupal.org] On Behalf Of Mike Booth
Sent: Friday, March 07, 2008 7:00 PM
To: documentation at drupal.org
Subject: [documentation] Proposal for a "Contributing to Drupal"
handbooksection

Fellow documenters,

As part of the Drupalcon Boston code sprint, a group of us (including  
add1sun, senpai, jacobroufa, maureen, mechfish, and others) discussed  
a new organization scheme for a central "Contributing to Drupal"  
section of the Drupal handbooks. This email is intended to document  
our thoughts for further discussion.

-----

There are many existing handbook pages that are stuffed with valuable  
information for potential contributors to the Drupal project -- but  
many of those pages are confusingly named, miscategorized, or  
redundant, which makes it difficult for new users (or even veteran  
users) to find them. The proposal is to create one unified document  
tree for Drupal contributor information, copy many existing doc nodes  
from their widely-scattered current locations into the new tree,  
consolidate redundant pages, and write new and better introductory  
landing pages which will guide users to the proper subsections of the  
handbook.

We propose that there be a new handbook section, titled "Contributing  
to Drupal", with the following top-level subsections:
     Get an Account
     Talk With The Community
     Use the Issue Queue

     Report a Problem
     Suggest Features

     Write Documentation
     Test New Features

     Contribute Themes
     Contribute Code

(These titles are tentative and may not be quite what we want. Feel  
free to suggest more alternatives and to point out what we missed.)

-----

Here are some more detailed descriptions of the proposed subsections.  
(CAUTION: mind-numbing detail ahead):

"Contributing to Drupal" (the parent link) links to a landing page  
that provides a general introduction to the Drupal project and the  
various roles that contributors can assume within the project.

"Get an Account" links to a page describing the advantages of having a  
Drupal.org account. Several folks at the sprint testified that they  
spent months lurking on d.o before they dared to actually register and  
start contributing forum posts, issues, docs, or code. So it's a high  
priority to specifically welcome and invite new d.o registrations.

"Talk With The Community" (originally titled "Communication" -- is  
there a better title for this?) links to a page describing the various  
ways to communicate within the Drupal community -- including, but not  
limited to: Forums, IRC, mailing lists, the issue queue, Pro Services  
listings, and a list of important external sites (e.g.  
groups.drupal.org, the Dojo).

"Use the Issue Queue" has several subsections. The landing page  
describes what the issue queue is, how it is used, what kinds of  
things it is for, who is allowed to use it,  and where it is (perhaps  
with specific links to the "Report a Problem" and "Suggest Features"  
pages, described below). Subsections can describe: where and how to  
search the queue; guidelines for posting, updating, revising,  
accepting, and closing issues.

"Report a Problem" links to a landing page which describes how to  
report a problem using the issue queue. It's important to provide a  
specific link for this, rather than just a single "issue queue" link,  
because new visitors don't know what the issue queue is yet!

"Suggest Features" links to a landing page which describes how to  
suggest a new feature using the issue queue. Again, this can be short  
and sweet, but it's important to provide a task-specific subsection  
and landing page which guides new users to the issue queue.

"Write Documentation" has several subsections: how to write a new  
page, how to edit pages, how to delete or reorder pages, how to file  
complaints about pages, etc.

"Test New Features" has several subsections describing: why we need  
testers, how to download and install patches, how to test thoroughly,  
how to write up patch reviews, where to file reports of problems.

"Contribute Themes" will describe how to submit new themes. It may  
have several subsections, analogous to the "Contribute Code" section  
described below. I'm a bit concerned about the title of this section  
-- "themes" may be a bit too much of a Drupal jargon word -- so feel  
free to suggest a different title.

"Contribute Code" has several very substantial subsections:

   - "Fixing Bugs": has further subsections which describe:
      -- how bugs are reported (i.e. a link to the "Report a Problem"  
section; see above);
      -- how to read and respond to existing bug reports (i.e. a link  
to the "Issue Queue" section; see above);
      -- how to download snapshots;
      -- how to download via CVS;
      -- how to apply a patch;
      -- how to roll a patch with "diff";
      -- how to roll a patch with CVS;
      -- how to submit a patch, review a patch, and when and how to  
mark one ready for commit (i.e. a link to the appropriate sections of  
the "Issue Queue" documentation; see above).

   - "Creating and Maintaining Modules": has further subsections which  
define a "project" and then describe all the details of creating and  
maintaining a project on Drupal.org. It will include a great deal of  
Drupal-specific CVS documentation, which should be broken down by user  
task and goal (e.g. "here is what to do when you want to upgrade a  
module from one Drupal version to another"). Each CVS task page should  
hew to a fairly standard pattern: a conceptual introduction ("Now we  
are going to create a new branch; here is what a branch is and when  
you should create one."), a detailed recipe ("here is the typical list  
of commands that you would use to create a branch"), an FAQ or two, a  
list of pitfalls, and a few links to more detailed CVS documentation  
(which may be in the "Introduction to CVS" section, described below,  
or elsewhere on the Web.) dww's existing docs, particularly those from  
his recent Drupalcon presentation, will provide most of the raw  
material for this subsection.

   - "Introduction to CVS": a subsection which is intended for more  
general, less task-specific CVS information: what CVS and version  
control is about, what specific tools are available, and so on. (We  
may want to retitle this "Introduction to Version Control" and  
incorporate all the information on alternative VCs that has been  
gradually accumulating in the handbook, or we may prefer to keep all  
that alternative info in a different subsection, or someplace outside  
of this handbook section altogether. )

Thanks to everyone who contributed to our discussion.

   Mike Booth (mechfish)

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/