quo vadis, docs

[Matthias Clasen <matthias clasen gmail com>]

Hey,

I spent some time last night to update the sound section of the user
guide to match reality. After that, I spent some more time to look
over the user guide and compare it to my desktop. The results, I must
say, are shocking.
Here are some highlights:

Mouse preferences
 - button, motion tabs are now general
 - timeout is now double-click timeout
 - pointer theme has moved to appearance capplet
 - a11y tab is now here

Keyboard preferences
 - keyboard tab is now general
 - separate group is now separate layouts
 - separate layouts is above selected layouts
 - a11y and mouse keys tabs are now here

Login photo no longer exists

Printing Preferences does not exist

A11y
 - assistive technology is now assistive technologies
 - screenreader magnifier, on-screen keyboard are now in perferred apps

Keyboard shortcuts
 - misses Accessibility section
 - adding shortcuts is missing

Screen resolution
 - multi-monitor functionality not mentioned
 - detect monitors button not mentioned
 - mirror screens checkbox not mentioned
 - rotation not mentioned
 - make default no longer exists
 - show in panel not mentioned
 - apply button not explained

Preferred applications
 - is now organized in tabs
 - multimedia player not mentioned
 - a11y apps not mentioned
 - start in terminal is now run in terminal

Desktop background
 - now part of appearance

Font preferences
 - now part of appearance

Menus and toolbars
 - now part of appearance

Theme
 - now part of appearance
 - theme:// no longer exists
 - custom theme now includes color and pointer

Window preferences
- titlebar action not mentioned
 - should have cross-reference to keyboard docs explaining the modifiers

Network settings does not exist

Network proxy
 - advanced configuration tab is now ignoerd hosts

Sessions
 - show splash doesn't exist anymore
 - prompt on logout doesn't exist anymoer
 - automatically save is now automatically remember running applications...
 - named sessions no longer exist
 - current session tab no longer exist

Take screenshot
 - doesn't mention copy to clipboard
 - doesn't mention drag-and-drop
 - doesn't explain --interactive, --remove-border, --delay=seconds

Nautilus
 - using removable media section is severely outdated
 - views preferences misses default zoom levels
 - media tab is not mentioned

I did a review of the admin guide a while ago, with similar results.
Some of these are minor details, but many of the major UI revisions
date back 2,3,4,5 releases. That leads me to some provokative
questions:

- If the docs team doesn't have the man power to follow major UI
changes, why bother with a UI freeze at all ?

- Are we just waiting for some corporate sponsors to pick up the docs
where Sun left them many years ago ?

- Should we just ditch the docs and declare the UI self-explanatory ?

- Is there anything that can be done, short of transmutating hackers
into technical writers at next guadec with the help of poisoned beer ?


Matthias