Tuesday, May 1
I’m thinking, far from the first time, about how few open source projects meet
a certain standard of practical openness:
Can a user unfamiliar with the project start with the published source code and
the included documentation, and wind up with a working installation?
The answer is “no way” a lot more often than it should be.
I’m all too aware that the full context it takes to build a lot of software is
a pretty hard thing to explain in a README. All the same, if you’re working on
a project of any size, maybe you ought to ask yourself some of the following:
Have I documented, in full, an up-to-date list of every environmental
condition that a user will have to manually obtain in order to build,
install, or run this code?
Is it clear what environments this code is developed in, and where it’s
known to run without issue? Am I being brutally honest about this part?
Is it clear what version of everything I used?
When was the last time I tested the installation procedures in my
documentation in a clean environment? Has it been since the last time I
changed dependencies or configuration requirements, no matter how
To what extent am I relying on implicit details of some OS, distribution,
virtual machine, container, configuration management tool, package, init
system, etc., without communicating those details to the user?
If a user is unfamiliar with details of a language, package manager, build
system, or other tooling, are they pretty much just SOL? If
so, is my software of interest to anyone outside of my specific technical
community, narrowly defined? Is there any potential that it will need to
be supported, for example, by admins or ops people who don’t share my
context, for use by some less technical audience?
If I personally returned to developing the software after leaving it
untouched for two years, how many problems would I be required to solve
from a combination of my own patchy memory, search engine queries, and
painstaking software architecture?
Are there any required environment variables, config file values, or
command-line parameters that are for some reason undocumented?
Am I posturing like a link to some automatically extracted API
documentation is a useful substitute for a real user manual?
Did I just publish a command-line utility with a crappy builtin help system
instead of a real man page?
I could go on like this for a while, but I suppose the point is clear enough.
If it sounds like I’m advocating a stricter standard than I usually manage to
live up to myself, well, that’s probably fair. Still, I think we could all
probably do better.
technical :: p1k3 /