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 _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
