I recently needed to do something to our MoinMoin-based wiki. As it was currently configured, doing that thing was a parade of annoyance, so I wound up rummaging through the configuration options and found one that significantly simplified my task. Now, suddenly, I had a dilemma.

Our existing MoinMoin configuration didn't have this option turned on, and the person who configured our MoinMoin instance isn't around any more to be asked questions. So, had they overlooked this option when they set up the wiki, or had they tried it and discovered that sadly it didn't actually work or worse, had some undesirable side effect elsewhere?

(We have documentation on the configuration settings that they use, but as common it covers what got changed from the defaults. And this option defaults to off.)

So, I have a suggestion: when you are documenting how you configured something, you should take a moment to write down all of the attractive-looking options and approaches you tried out but that turned out to not work, caused problems, or whatever. Otherwise you risk someone coming along later, seeing that you have not done something that will make their life easier, turning it on themselves on the assumption that you overlooked, and having things explode.

Conversely, documenting things that you have tried but not used gives those people some confidence that you actually overlooked this convenient option and they can thus turn it on with only ordinary precautions and concerns.

By the way, your future self is likely to be one of those people (unless you have a better memory than I do for things that I tried and rejected).

PS: this generalizes to more than software configuration files.

(To add a conclusion to my MoinMoin story, so far it seems that the configuration option I found works fine and has no bad side effects. I'm happy.)