[drupal-docs] plans for moving forward with Drupal docs

[Charlie Lowe]

Thanks for everyone's support in Dries's decision to make me 
documentation coordinator. I want to start off by saying that some many 
people have been doing lots of hard work, but we seem to be at a 
crossroads and some decisions have to be made. I'm afraid I can't 
satisfy everyone's position on the following issues, so hopefully 
everyone will at least agree that a common plan is better than many 
plans. I'd also like to apologize for the length of this email.

To start off, here are a few points:

* We have a better set of collaborative authoring tools and 
communication technologies here on drupal.org--forums, project issues, 
collaborative, book mailing lists, etc.--than almost any distributive 
collaborative authoring project ten years ago. We can write effective 
documentation with what we have.

* We are part of an open source project where it is important that we 
create a process which includes as many members as possible.

* As part of an open source project, it's good to eat your own dog food 
when possible.

Right now we have documentation construction spread across a wiki and 
two versions of the handbook. We don't have a clear process for 
submitting documentation. Not only that, but most of what we have been 
doing is hidden from the rest of the community unless they happen to be 
on this mailing list (and in some part on drupal-devel).

People have also been working *very* hard (kudos to everyone!), and we 
need to simply the process so that when people work hard, better and 
more documentation gets written. I think we can all agree on this even 
if everyone doesn't agree with all of my points above or the decisions 
that follow.

So there are three main issues to address

1) Where does documentation created by the drupal-doc team reside and 
get constructed? This would include guidelines for producing 
documentation, admin/help, handbook text, etc.

2) What is the process/workflow for creating documentation?

3) What is the process for restructuring the handbook?

Dries has already stated that he would like documentation construction 
to happen and documents to reside on drupal.org--not even on a subdomain 
of drupal.org, but the main drupal.org site. Since I agree with Dries, 
and given all the reasons above this, this will be our new policy. That 
doesn't mean that we shouldn't appreciate the resource Boris has offered 
with the wiki. But we have plenty of good technology here to use. 
Besides, other people will join the documentation team. We'll get more 
good people like Djun who want to write docs and code, and in doing so, 
refine the tools that we use. If someone wants a wiki, find a way to 
build a proper one into Drupal. I'm sure everyone is in favor of that :)

This helps out with (2) a lot since it leaves us with fewer options. The 
Drupal handbook will obviously be the repository for our documentation. 
And we have a few means to discuss proposals and drafts of 
documentation--mailing list, forums, and project issues. We just need 
now to outline how we will use these technologies. Once we do, I'll 
writeup guidelines so that we can tell new drupal-doc participants: 
"read this to know how to get involved."

As for (3), the whole handbook restructuring thing has been through a 
lot of revisioning of how the project should be done starting with a 
whole different subdomain site. In all of that, the main two concerns 
have been about archiving (for versioning) and how to do a massive 
restructuring without disrupting drupal.org doc users. As for archiving, 
Djun's already produced a pdf version of the handbook; we can archive 
the entire handbook at anytime by using the printer-friendly version. I 
know that doesn't help with the shortened admin/help that now links to 
the handbook, but the obvious solution to that is that the admin/help 
should be longer and include the handbook docs. Besides, we probably 
don't want to produce an entire new collaborative book for every version 
of Drupal each time there's a new release just so those links work. It 
looks like the versioning problem is not going to be resolved until 
someone comes up with a technological solution.

That leaves how to do a massive restructure/edit without causing a 
problem for those that use the handbook as a resource. The V2 of the 
handbook was a technological solution. Create a second version, edit, 
restructure, get feedback, edit, restructure and so forth. All kinds of 
problems with that: copy pages back and forth, dead links, etc.

There is a better way, a more efficient way, one that is a writing 
solution to this problem. Bryan posted an outline of the About section 
for V2. I just posted a separate restructuring proposal for the original 
handbook About section. Whether or not we have a V2 version of the book, 
a proposal of some kind--an outline of the new book structure with some 
thinking behind the structure--is a way for everyone to be involved in 
the process: Anisa, Djun, Bryan, Kieran, Robin, Andre, Dries, etc. We 
have a huge resource of people who can help with getting large sections 
of the book outlined before writing begins; proposals such as these are 
commonly used as a starting point to manage large projects effectively. 
Dries has already asked why don't we just rework the original book. This 
is the means to do so.

So this is where we are

1) The focus of the drupal-doc doc team is to manage document and 
documentation authoring using the tools available on drupal.org.

2) We need a process for getting feedback on drafts of documentation and 
sharing proposals (I think it's safe to say that the documentation team 
members can individually decide *if* they need feedback on a draft; we 
may not need to do so often).

3) We need to plan revision/restructuring of the various handbook 
sections so that we minimally disrupt users of the handbook. A short 
proposal with an outline would allow the other members of the 
documentation team to assistn in planning what needs to be written 
before the writing starts. Functioning as a guideline, such a text would 
also allow multiple people to more easily work together on the same 
section of the handbook at the same time.

So that this doesn't get too crazy with emails trying to respond to too 
many different issues, I'm going to send out two different emails 
tomorrow after people have had a chance to digest this asking for 
discussion of how to move forward with (2) and (3).

Charlie Lowe