[wp-docs] Back up the truck

[Chris Waigl]

I will not contribute on this topic after this post: Meta-discussions
on what we ought to discuss are sure to bog us down. But I need to get
this on the record because I think you're touching on a problem that
has plagued the WP doc for a long time.

I am also sure you won't confound disagreement with a personal attack.
I'd never do the later on you -- I hope you know this.

This said, here my opinion:

1. We dearly, desperately need a structure.
2. We need it for two reasons: a) users won't consistently find what
they need even in docs written by angels if the doc isn't structured;
b) people like me won't efficiently contribute to something that
doesn't have a structure.
3. To stay in your metaphor: yes, content rules, but if the editors
don't tell the authors what to write, they'll end up with a fashion
magazine, two murder mysteries, a tabloid article, a NYT article, half
a dozen of science fiction novels and and two disjointed volumes of an
encyclopaedia, each covering a different part of what you need.
4. So we don't only need a structure, we also need (an) editor(s) who
enforce(s) the structure, if only by connecting the different pieces,
assigning them to a category (subsection, whatever), rewrite pieces
that employ a style or language inappropriate for the intended
readership -- or dispatching this task to another author who'll do it.
5. The need for a structure doesn't mean that different subsections
can't be written in varying styles. We can have step-by-step
instructions with screen shots, comprehensive guides to big topics,
and small, targeted question-and-answer pages.
6. Ideally, we ought to prioritize among those. Personally, I think
the big guides ought to be written last, but by all means lets
incorporate those that are already.
7. Last, having a structure doesn't mean to have a list of article
titles that's set in stone and has to be worked down one by one. It
just means that if someone writes something, they know where it goes,
what it's connected with, and whom it addresses. Reorganising later
means uninspired (or too narrowly inspired) contributors, and doing
three times the work in the end, because everything has to be
rewritten.

Oh, and if you want, I'll tackle the Loop.

C.

P.S.: It's true that I'm a big-mouth here, given how much work, and
excellent work, you've already done compared to the little bits I
have. But I simply can't do much more in this haphazard fashion, at
least nothing I wouldn't despise later.


On Tue, 14 Dec 2004 09:06:29 -0700, Craig Hartel <craig at nuclearmoose.com> wrote:
> It's good to see more discussion going on about the documentation. However, I
> see the process bogging down already. I'm sorry to be a stick in the mud, but we
> simply can't afford to spend time debating structures and whatnot. We need
> content. The organization can come after. [snip]


-- 

Chris Waigl
blog: http://serendipity.lascribe.net/
experiments: http://chrysalidesque.f2o.org