Bug#803303: general: Standardized troubleshooting
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)