GNOME Bugzilla – Bug 532162
Documentation of many applets is... useless :-(
Last modified: 2010-12-30 14:25:34 UTC
Documentation Section: nothing that is not immediately obvious to anyone who makes ti to the documentation Correct version: It should go little bit deeper than just describing things that are simply obvious and just taking place. Every applet should tell where it gathers things so intermediate users are able to fix them with the help of the documentation. This applies to: CPU Frequency scaling monitor, there is no advice what to do if something is not OK (like missing governors etc). I think that the applet should point to the daemon and config file it uses. Disk mounter for instance doesn't tell that it parses /etc/fstab file (useful if one wants to get rid of meaningless icons). Screen resolution (not an applet) doesn't tell what to do (how to edit xorg.conf), if one wants to add some mode that is not available one knows that the hardware is capable of it. Other information: I think that most documentation entries should contain section "for more experienced users" written by developers. Sometimes things "simply don't work" and one can't get an idea what to do without being online
Screen resolution is part of the GNOME Desktop Guide section on preference panels, isn't it? > I think that most documentation entries should contain section "for more experienced users" written by developers. Good idea! And one thing we could move to this is the bit about how to start the app from the command line which is in the 'Getting started' section of most manuals, where just looks geeky. > written by developers. You might need some sort of array of pointed sticks to get this part done.
Closing as this report is too vague to define when it would be "fixed". If you have a concrete list of things you want to see covered by the docs, please provide it. The docs are for average users though. Stuff like /etc/fstab could be mentioned in a note (in Mallard docs) but not as part of the "normal" manual content.