I attended a review for a manual that taught how to upgrade our network configuration file from the previous release to the upcoming release. The manual had very tedious instructions. The tech writer had captured the details and wisdom from the technical support people who had been configuring and upgrading systems.
The old format was a directive name followed by a comma-separated list of parameters, with fixed positions and multiple commas for unused parameters. The new format I had designed had a directive name and keyword=value free-form on one or more lines of text. This made the configuration file very clear and much less error prone.
I said at the meeting that we should, “Program computers, not people!”
I saw that our old format was like macro calls in our assembly language and we could use the assembler’s macro preprocessor to parse the old directives. We could write macro templates that took the fixed-format parameters and wrote them in the keyword=value neat, self-documenting syntax.
The result of that meeting was that the manual was canceled, and the support staff and I would work to make the MIGRATE.EC (execution command file) for the customers to use to upgrade to the new configuration file. This worked very well, and we received some awards for this project.
Later, at our users’ conference, one of the support people happened to run into an instructor from our education department, located in another city. He asked how our new release was doing. The reply was that it was great, and the customers really like it. The trainer said he was surprised because no one was taking his configuration upgrade course. He had turned the first draft of the manual into a course and he expected many customers to take the course. That manual had been replaced in the release bulletin by a one-line command:
EC MIGRATE oldfilename