Re: Role and function of the docs team

[Alexander Shopov <ash contact bg>]

Joachim,

I totally agree with you.

> Ever six months, gnome reaches feature freeze. The doc
> writers go forth and explore every single bit of the
As you later correctly say - this is impossible. Documenting from the 
outside in is not producing meaningful docs - if a documenter is able to 
deduce things from the outside - so would the user. If a documenter was 
not able to deduce things - most probably the most needed documentation 
would be lost.

> new gnome, and bring the docs up to date accordingly.
Docs laaaag.
Their translations - much more so.

> 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.
Still - easing the access to builds will alleviate the situation somewhat.

> 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.
And people burn.

> 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.
Unsurmountable problems are also putting off people.

> 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.
ChangeLogs help, but not completely as the connection between code and 
user point of view is often murky.

> 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 developers should just sketch the new functions - not sth like 
full docs - just an overview.

> I think the docs team should be notified of interface
> changes as they are made, preferably with screenshots.
Yep. If there are notifications of string breaks, there could be 
notifications for interface breaks.

> 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.
Even developers do not push everything up to CVS versions - maybe some 
libraries and few apps. Doc writers have to push up everything.

Kind regards:
al_shopov