Nothing sucks enthusiasm for a job faster than a frustrating search for information you need to do the job that turns up empty or irrelevant. Even worse is when the information you find is outdated or even lies to you!
How Systems Do It
While looking for information I needed at work recently, I was struck by how similar it is to systems looking up data.
I recall doing a database optimization once where an SQL statement referenced a table that wasn’t indexed properly. It actually had to “scan” a table with hundreds of millions of records which took hours and impacted everything else which ran on the database.
For systems, scanning for data sucks which is why we use indexes. Even faster than indexes however, is if the information can be found “deterministically” or “algorithmically”. This can reduce the time from milliseconds to microseconds which can be important if executing thousands or millions of times. Hashing schemes are good examples of this.
Humble Human Searches
For humble humans looking for information, scanning a large repository of documentation for information you need sucks too. If the company documentation is poorly organized or poorly indexed, there may be no other alternative and might take hours. Organizing documentation takes work, but is paid off many times for all the users.
Even better, is if the information you need to find matches a common pattern and can be determined “algorithmically” as well! Hostnames following a common pattern or well-known conventions that remove the need to “look it up” or “figure it out” are some examples.
Convention over configuration is an example of the principle of least astonishment and can help by not requiring any lookup at all!
Example
A case in point is looking up the information on an internal command which you need to execute. If the commands have been developed with in-house with a common convention, you are in a happy place!
Alternatively, you may need to do one or more of these things..
- Ask a colleague. With remote work, this can be difficult and is synchronous. You may be blocked and have to wait..
- Buried somewhere in company documentation, which can be difficult if not well-organized;
- Git repo with a README.md file;
- The source code, if it’s a script;
- Manpages or gnu info, Not used as much anymore unfortunately;
- Execute with no arguments, not a useful convention, as this might be normal and be harmful!
- Execute with “-h” or “–help” this is a commonly used convention.
Probably best is to document via commonly used/known command line switches for a short summary and your normal company documentation for deeper details. The git repo may even be a convenient place and a reminder to the engineer to update the documentation as well as the code. Perhaps even provide a link to the deeper documentation in the command summary!
Be sure to limit yourself to one standard..
IMHO, tools aren’t complete until documented..
…and, not this!
