Role and function of the docs team

[Joachim Noreiko <jnoreiko yahoo com>]

This is something that's been on my mind for a while,
and I was going to leave it till after the release,
but the new default theme is basically the camel's
back.

Correct me if I'm wrong, but this is the picture I
have of how the wider gnome project considers the docs
team's function: 

Ever six months, gnome reaches feature freeze. The doc
writers go forth and explore every single bit of the
new gnome, and bring the docs up to date accordingly.

I don't think this model works. We didn't manage to
get everything done for the 2.14 release earlier this
year, and I'm really rather worried about this coming
release. I see the lack of docs for Orca really
messing up gnome's accessibility. 
We're operating on a skeleton crew, and even if we had
a full complement of doc writers, equipped with easy
access to current builds (such as VMs), I don't think
it's the correct way to go about it.

Reason 1: it's a big crunch. The GDP almost shuts down
for months, and then has to go into overdrive to get
the work done. Volunteers lose interest when there's
nothing to do, and don't necessarily want to work in
the few weeks leading to release. It's also stressful
and non-fun. We need to spread the workload throughout
the cycle.

Reason 2: too much time is wasting feature hunting.
Documentation writing shouldn't involve trying every
single bit of an application on the offchance
something has changed. It's a far more efficient use
of our time if we have a list of what's changed.

We need to be able to plan ahead, and we need to have
a better picture of what we're doing.

There are a few applications with roadmaps on the
wiki, but even those aren't that useful to doc
writers. I might see a note on gedit's roadmap saying
'New Python Console', or 'FileTree sidepane plugin',
but to get more information, I'd have to sign up to
yet another mailing list, try to get some details, and
so on. I'm on too many gnome mailing lists already,
and I hate the damn things. (I'm not picking on gedit,
by the way, they just happen to have a roadmap. In
fact they've been great at answering my questions on
IRC.)
Take for example the new button in the Nautilus path
bar. This was implemented at the end of July. Given a
screenshot to go by, the required changes could have
been made to the User Guide back then. As it is, the
bug is still open (348841, by the way).

I think the docs team should be notified of interface
changes as they are made, preferably with screenshots.
Basically, the docs list should be getting details of
new features and changes throughout the cycle, not
just during freeze. Developers need to understand that
writers probably don't have access to builds, and will
need screenshots -- not production quality ones, just
so we can see what's going on.
I think this might not be a popular proposal, but we
need to do what's necessary to make sure gnome comes
with proper documentation, so developers at large need
to realize there aren't any magic documentation elves.


		
___________________________________________________________ 
All New Yahoo! Mail ? Tired of Vi gr@! come-ons? Let our SpamGuard protect you. http://uk.docs.yahoo.com/nowyoucan.html