[documentation] Issue Queue vs. Listserve, Roles for Each

[Angela Byron]

Shai Gluskin wrote:
> @meitar has raised an important question, how does one know whether to 
> post something to this docs list serve or to the issue queue? He's also 
> raising the issue of lack of visibility regarding the list serve, which 
> is relevant to the propsed new block for doc pages and being discussed 
> there <http://drupal.org/node/263767>.
> 
> This is how I would break down the "When Listserve? When Issue Queue?" 
> question.
> 
> *Doc listserve*: /discuss/ docs strategy, approach, overall problems, 
> announcements for IRC Docs meetings or other Doc meetings like a docs 
> sprint.

...and for fleshing out an approach enough to make it actionable. See below.

> *Issue queue*
> *for non-documentation team members:
>  --file as "bug" something that is a mistake in the docs section of the 
> d.o. handbook. (If the person is on the docs team, that person should 
> just fix it; no need to post in the queue.)

Actually, docs team members can (and, imo, should) do this just as well. 
It's best to have a list of all of the docs problems that were too 
complicated to fix in one quick pass in one place.

>   --Submit request to join the documentation team.

Sadly, yes, but I'd love to figure out a better way for this to happen. 
NOT in this thread though, please. :D

> *for anyone:
>   --make any formal request to change the way the Drupal project deals 
> with documentation (sometimes these are actually filed in the webmasters 
> queue or the infrastructure queue)

I would say sure, but *only* after consensus is reached on the mailing 
lists. If issues have a clear, unified direction on something, they can 
usually be implemented quickly. When they don't, they just turn into 
another noisy discussion, but this time each reply is e-mailing several 
dozen more people than just the folks on the docs list, including folks 
like Derek Wright, who are *very* busy with many other things, like 
keeping our download system working and CVS from falling over.

This is why I advocated for moving the question of "Why aren't revisions 
turned on for anon users?" to the issue queue, but NOT the block 
question, because the docs team (still?) hasn't come to consensus about 
what it wants to do yet. The place to talk back and forth about the best 
way to do something is on the docs list, and once consensus is reached 
on an approach, *then* move it to the issue queue (ideally, with a patch).

>   --submit support request when desiring help in writing a document.
>   --submit feature request for needed doc that doesn't exist -- but 
> person submitting can't or doesn't want to write it. (If person was able 
> to and wanted to, person could just add it without filing an issue).

Yes, and probably also things like "The Multisiter docs really could use 
some clean-up. Here's how I envision it..."

But I file *critical* bug reports against missing API documentation 
(like hooks), example code that doesn't compile, and stuff like that, 
but I'm thinking about moving those to the "Drupal" project queue under 
"documentation" component instead, for increased visibility by the 
developers who were the ones who didn't document/fix them in the first 
place, and so the next version of Drupal doesn't go out again with like 
25 hooks undocumented. :P~

> There is overlap and some duplication in that the responses to a formal 
> proposal made in the queue will certainly contain opinions about the 
> overall approach and strategy of docs, which may previously have come up 
> on the list serve. But when they came up on the list serve, it was part 
> of brainstorming or general discussion, not in the context of a formal 
> proposal, and so it's okay that they are repeated on the issue queue.

I disagree w/ this. Get the formal proposal worked out on the discussion 
list, and when it's *actionable* then move it to the issue queue.

> Another way to think of all this is that the list serve is for vetting 
> and the queue is for action.

Exactly! :)

-Angie