Jacob M. Roufa

Well, Drupalcon Boston 2008 is now over. I had a blast, enjoying my time there immensely. There were some fantastic sessions that provided great motivation for me. As I declared a few posts ago, I would like to focus this blog on helping the newcomer to Drupal. I was blown away by two sessions in particular, Documentation Team Lead Steven Peck's Documentation - challenges, travails and myths session and Addison Berry's Contributing to Drupal: A Guide for Everyone session. What was even more exhilarating, however, was the code sprint on Friday. Four days of theorising followed by one day of extremely focused action.

I didn't actually write any code yesterday, as the name code sprint might imply. I did get to work directly with Steven Peck and Addison Berry, among other people. What amazes me most about this community is its level of self caring. The Drupal rockstars and geniuses are all more than happy to not only sit and hear what you have to say, but they are also incredibly action oriented and love to have everyone involved. Very motivating and down to earth people.

Unfortunately, I was unable to stay past 1pm brong>ecause of my flight plans. I did get to help plan out some community changing stuff though. As seen on the Documentation mailing list :

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)

Many thanks to Mike for writing this up and contributing to the flow of thought that we all had going yesterday morning. I really can't wait to see where this goes. These changes represent a fundamental shift in the way Drupal is being presented to the community. The change in the way we're documenting everything is going to be huge.