Tag: Information Studies

Assume the Documentation is Incomplete

cbcrenshawLeave a comment

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.

The Mountain of Military Knowledge

cbcrenshawLeave a comment

I got this link in a Vice newsletter today: “Air Force Video Explains What a Penis Is.” 

Image from the U.S. Air Force via Vice.

Ha. Nice, Vice. That’s a funny one. It practically clicks itself. 

When I was through laughing, though, I started to wonder. If you surfaced all the information and knowledge the United States military has amassed, described it, and made it accessible, how big would the resulting library be? Would it rival the Library of Congress? What if you included the literal mountains full of classified information? 

Doctors in fatigues offering up a straight-faced explanation of the penis makes for a funny video, sure, but think about the context of that video. That penis video–a remarkably well done bit of public health information, I’m not too cool to admit–was likely produced as part of an overall health information strategy that included other videos designed to meet specific training goals for Air Force personnel. Someone had to draw and render that 3D phallus. Someone wrote the text, someone storyboarded the video, someone cast the doctors. Someone set up the studio. Someone made arrangements for the doctors to come and record their parts. Someone filmed the segments. They did multiple takes. Someone else–probably more than one someone–edited the video. Someone else posted it on the web. On and on it goes, every day, and that’s just videos. The Army and Navy probably have their own versions of the same thing, and each of them is just one example of hundreds of thousands of pamphlets, manuals, SOPs, videos, audio recordings, books, specifications, and other resources the military produced in just a single year. Multiply that by seventy-five years and you would have the Alexandria multiplex of knowledge accumulation and dissemination the modern American military has undertaken since the end of World War II. 


That’s not ephemeral information, like emails and phone logs, but strategic media created for the express purpose of knowledge transfer and managed according to long-term retention and preservation policies. Where is all of it? Vice mentions DVIDS, the “Defense Visual Information Distribution Service,” but that’s just visual information. The various service “doctrine” websites are another source, and of course the National Archives and Library of Congress have millions of items. Much of this knowledge is accessible, but it is extremely decentralized. What would we do with it all if it were described and catalogued? What if it was semantically linked? Would we just make fun of it, or would we make use of it?

Research of Note: Data Activism

cbcrenshawLeave a comment

Gutiérrez, Miren and Stefania Milan. “Playing with Data and its Consequences.” First Monday 24:1 (2019). https://doi.org/10.5210/fm.v24i1.9554

Scholars, advocates, and social critics frequently describe data as a structure of power used against citizens and the powerless online. In their article in the most recent First Monday, Miren Gutiérrez and Stefania Milan invert big data, arguing that “Citizens, activists and professionals alike embrace innovative data-related practices at the intersection of the digital and the informational, embedding data and ways of playing with data in their activities.”

Data is undoubtedly used to oppress and exploit, but Gutiérrez and Milan show how it can be used to advocate for the rights of the less powerful, as well. Recent work in critical studies of neoliberalism–I’m thinking about Byung-Chul Han’s ideas, in particular, which are very nicely summarized in the Verso essay collection, Psychopolitics–paints a nearly hopeless picture of privacy in the radically transparent world that social media has wrought. While it does not occupy the same intellectual field, this research introduces a necessary critical counterpoint.