[documentation] Proposal for a "Contributing to Drupal" handbook section
mike at michaelfbooth.com
Sat Mar 8 00:00:27 UTC 2008
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
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
Test New Features
(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)
More information about the documentation