Package: general Severity: wishlist Dear Maintainer,
I've been using Debian on all my machines for many years and am generally very happy with it but I recently realized that my experience could have been even better (both for me and for the maintainers of all the packages I use) if it were easier to figure out how to troubleshoot problems. Concrete suggestion: add a "TROUBLESHOOTING" section in the manpage of every program, explaining how to get more info about what's going on when the program doesn't do what the user wants. I've often gone through steps like: 1- Program Foo crashes/hangs/misbehaves/younameit when I do something. 2- Search the web to see if someone else bumped into the same problem and found a fix for it. 3- No luck, so I report the bug to Debian or to the upstream. 4- Someone gets back to me telling me to set env-var FOO_DEBUG=99 then re-run the program and show her what is reported in file .foo_debug_log. My suggestion is to try and skip step 3 and 4, replacing them with "man foo; then look for the TROUBLESHOOTING section". Usually this troubleshooting info can be found somewhere, but every program puts it at a different place, making it difficult to find. Furthermore, the troubleshooting info needed may go further than the program itself, e.g. when the program is not started from the command line but via some other mechanism (inetd, systemd, gnome-shell, ...). In the longer run, it would be even better to try and standardize not just the place where the troubleshooting info is located, but the way troubleshooting is done (e.g. always provide a "--troubleshoot" command-line flag which always gives the output at "the same place"), so that I could for example do "systemctl troubleshoot gdm3" and systemd would know how to start gdm3 in order to get debugging info. But a good first step seems to be to start collecting the troubleshooting info at a standardized place (e.g. the manpage). Of course if you prefer putting that info in /usr/share/doc/<pkg>/TROUBLESHOOTING, that's fine as well. As long as it's always the same place. -- System Information: Debian Release: stretch/sid APT prefers testing APT policy: (990, 'testing'), (500, 'unstable'), (500, 'stable') Architecture: i386 (x86_64) Kernel: Linux 3.16.0-4-amd64 (SMP w/2 CPU cores) Locale: LANG=fr_CH.UTF-8, LC_CTYPE=fr_CH.UTF-8 (charmap=UTF-8) Shell: /bin/sh linked to /bin/dash Init: systemd (via /run/systemd/system)
