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.

Google Bard’s Gothic Hallucinations

cbcrenshawLeave a comment

Yesterday I asked Google Bard the kind of question I’ve often wanted to ask a search engine.

“Imagine you are a professor preparing a graduate seminar on 18th- and 19th-Century British Gothic Literature,” I instructed the machine. “What materials would you place on the syllabus, including a combination of primary texts and secondary criticism and interpretation, and how would you group them?”

This is a complex question, but the solution—as I understand it—should just be a series of search queries in which the most appropriate results are mapped into the LLM matrix to produce the output. Because Google is the market leader in search, and I’m not asking Bard to display its “personality” like Bing/Sydney (the “horniest” chatbot, as The Vergecast would have it), I thought this would be an ideal task for Bard.

Boy, was I wrong. Here is the syllabus Google Bard produced.*

gothic-syllabus-from-bard-1Download

On first glance, this looks like a valid, if unoriginal, syllabus. Bard has identified some representative primary texts matching the query and has chosen to present them chronologically, rather than thematically. That is a sane choice. And those texts actually exist.

Now let’s look at the secondary literature Bard wants students to grapple with. Bard has selected the following texts:

  • David Punter, The Gothic Imagination: A Critical History of Gothic Fiction from 1764 to the
    Present Day     (1996)
  • Anne Williams, Gothic Literature (1994)
  • Stephen D. Gosling, Gothic Literature: A Cultural History (2000)
  • William Veeder, Gothic Fiction: A Critical Introduction (2005)
  • David Skidmore, Gothic Literature (2013)
  • Andrew James Smillie, Gothic Literature (2017)

“I would… group the secondary criticism and interpretation chronologically,” Bard says, “starting with Punter’s The Gothic Imagination, the first comprehensive critical history of Gothic fiction, and ending with Smillie’s Gothic Literature, the most recent critical history of the genre.” That sounds good, but none of these texts exist. Not one. Google Bard made up every one of the texts on this list, and several of the people listed there as well.

David Punter is, indeed, a scholar of gothic literature, but as far as I can tell has never produced a text entitled The Gothic Imagination: A Critical History of Gothic Fiction from 1764 to the Present Day. Anne Williams is Professor emeritus in the English department at UGA, but I cannot find an overview by Williams published in 1994 (though Art of Darkness:  A Poetics of Gothic, published in 1995, sounds fascinating). I can find no gothic scholar named Stephen D. Gosling, and obviously no cultural history Gosling may have authored. William Veeder was a professor at U. Chicago but never wrote Gothic Fiction: a Critical Introduction. And so on. None of these books exist.

Make of this what you will. I don’t think Bing or ChatGPT would do much better at this task right now, but it is only a matter of time until they will be able to deliver accurate results. In the meantime, the machine is confidently hallucinating. Caveat emptor.

Of course, I did ask Bard to “imagine” it is a professor. Maybe it took me too literally and “imagined” a bunch of books that would be great for graduate students to read. Perhaps I should have told Bard it is a professor and insisted that it deliver only real results.

There’s always next time.

* To be fair, Google warned me twice that this would happen.

The Haunted Delta

cbcrenshaw3 Comments

I am spending a couple days in Clarksdale, Mississippi. This morning I woke up and thought, the Delta is three-times haunted.

The Delta is haunted, first of all, by the absence of those who have left. Their homes crumble alongside the sinking highways, rotting to splinters among the rusted remains of their tools and toys and old cars and things. Now and again, an anachronistic busybody will roll down US-61 and reclaim a few of the old shacks for a museum, but the pickings are slim. The rot remains to remind the survivors of what has been.

The Delta is haunted as well by the significance of its past and the seeming insignificance of its present. Here in this room, the rough-hewn, wood-paneled parlor of an old sharecropper’s shotgun house, Muddy Waters stares at the Haint Blue-painted door from a poster on the wall above the bed. By the front door and on the bathroom wall, two separate travelers have commemorated “Flyover Country Road Trip” with permanent marker. Mark Twain and Muddy Waters imbued this place with meaning in the last two centuries. What animates it now but the spirit of those who have left?

Nature haunts the Delta, too. Last night a storm raged for hours outside the shack here. The wind poked and prodded at the old wooden panels, slamming the screen doors and creaking up and down the porch like a malevolent visitor in the night. In the lull, I could hear the wind rolling through the magnolia trees and across the vast black and brown field beyond like an intelligent thing. The spirit of the Mississippi River stalks the landscape here, ambivalent to the people hanging onto the black earth for life.

I love it here.

Cracker Barrel Ephemera

cbcrenshawLeave a comment

Things I can see on the wall at Cracker Barrel:

  • A trombone
  • A shotgun
  • A rusty woodworking plane
  • 2 wooden rolling pins, one with red stripes
  • An aqua-colored aluminum bundt cake pan
  • A stuffed largemouth bass
  • A framed Ray Charles album
  • A portrait of Etta James
  • A portrait of an unnamed middle-aged man in a double-breasted jacket
  • 4 cast iron skillets
  • 2 washing boards
  • 3 long-handled grill baskets
  • A large tin can labeled “Pure Lard”
  • 9 quart-sized cans of Orsi Pure Olive Oil
  • A tin advertisement for the Rio Grande Fence Company of Knoxville, Tennessee
  • Two wooden tennis rackets
  • A pair of water skis flanking a portrait of stunt skiers at Cypress Gardens in Winter Haven, Florida
  • A group portrait of the 168 members of the Nathan L. Strong Class of the Coudersport (Pennsylvania) Consistory of June, 1927