Jenkins is a pretty standard Java-based web app. The configuration settings are stored in XML files, and that configuration is manipulated using "easy to use" Web GUI.
The "old skool" UNIX-like way to keep configuration settings is in a text file, which is edited with an ordinary text editor, and is read by the program daemon on start or SIGHUP. This is considered "scary", "hard to learn" and "hard to use" by novices.
There is a big problem with GUI-only managed configuration, text file configuration has a major advantage.
I did not set up the Jenkins server or nodes. I am not the only person with admin access to it. Several other people have set it up, set up various projects in it, and added new nodes and new types of nodes.
As I work on it, and look at the existing configuration, I often find things that are "surprising", things that make me say "Is that right? That can't be right? Can it?". And then I have to spend time digging into it. Something it IS right, for reasons I didn't know at that moment. Sometimes it used to be right, but isn't necessary any more. And sometimes, it just wasn't right.
In a textual configuration file, you can put comments. The purpose of a comment is to communicate into the future, to tell those who came after you (including your future self) what you were intending to do, and why you selected some "surprising" option or way of doing things.
There is no good way to put comments into GUI or WebGUI configuration, even if it has a freeform field labelled "comments".
This entry was originally posted at http://fallenpegasus.dreamwidth.org/846029.html. Please comment there using OpenID.