Assume the Documentation is Incomplete

Here is a simple lesson from today: assume the documentation is never complete and plan accordingly.

I lead a small team responsible for supporting, maintaining, and developing enhancements for a complex IWMS (that’s Integrated Workplace Management System for the un-jargonated) used by the State of Florida to manage facilities. Though the state has only been using this system for about five years, it has been around for almost twenty years—and it shows. Every decision made by designers over the years, influenced as they have been by every passing fashion in web apps development, has left a residual mark on the system. There are some areas of the system where these marks are more apparent than others, but we run into them in unexpected ways every day. Perhaps coincidentally (but probably not) these little beauty marks are also the least documented portions of the system. Today, we encountered one while we were trying to figure out an alternative to the antiquated way this system handles data integrations through the API. The system uses a dummy user account, subject to the same password policies as the rest of the system, to update data. This means that we need to either, a.) change the system-wide password policy, which may make sense but we haven’t considered doing yet; or, b.) someone needs to provide new service credentials to agents using the API on a regular basis. As always, we asked: hasn’t someone else solved this problem already? Turning to the system documentation turned up no results, and this system is too niche for Google to turn up many useful results. As usual, then, we were on our own to find a workaround. 

I felt a little thrill when I noticed a “Service Only” flag on user profile pages. Someone, somewhere must have come up with a solution for service accounts, I thought. Maybe this flag overrides some of the system security policies used to protect human user accounts from the humans who use them! If browsing the documentation by topic and searching the contents for “API credentials” and variants didn’t work, at least this little flag clearly visible on the screen would be described somewhere and get us closer to an answer. 

That was not the case. The “Service Only” flag was not described anywhere in the system documentation. Undeterred, we did what intrepid developers and admins everywhere would do in this situation: turn it on and see what happens. We fired up the test environment, created a throwaway account, and made our way to the screen where the little flag lives–only to find that it is a read-only field. We could not turn it on. 

Fine. In this no-code system, if all else fails, you can dig into the data model, form elements, and queries to understand by inference how things work. We delved into the form and data model to find – nothing. The boolean flag simply exists in a read-only state. There are no workflows attached to it and no associations leading to or from it. 

Is this some sort of vestigial feature leftover from old versions to support legacy accounts? Can it be activated through some obscure menu somewhere else? Who knows? It’s not in the documentation.

I draw a few, interrelated lessons from this.

1. As an administrator, never assume the system documentation will have the answer you need. In the absence of holy writ from the vendor, develop procedures to mitigate your own ignorance.
2. As a developer, write. better. documentation. What’s there is never enough. Sure, writing documentation may not be your job, but at some point it will be your responsibility.
3. If it’s your job to write documentation, go through every button on every screen. Assume you have never written enough and give this assumption some weight when you decide how much more work to do before release.
4. As a support provider, give users the ability to suggest improvements right in the documentation. “Contact Us” on the page isn’t enough. Users don’t want developers to cede their authority by deploying a wiki, but some of the features of a wiki should be more widespread. I think the “Talk” pages on Wikipedia are a great solution for user feedback on documentation.

Here’s a good song to end the day. That “Walk On By” sample was all over the place back in the 90s, but this is a unique one.