Bob DuCharme joined Katana Graph as a technical writer in November of last year. He is an accomplished software developer as well as a published technical and popular writer. He’s been involved with semantic web technologies since 2002 and has written books on SPARQL, XML, XSLT, and operating systems for O'Reilly, Manning Publications, and Prentice Hall. Bob has written nearly 100 online and print articles about IT and is proud of never having used the word “functionality” in any of them.
Bob was recently interviewed by Nikhil Krishna of Software Engineering Radio, a podcast sponsored by the IEEE. They discussed aspects of creating technical documentation for software projects and how that undertaking has evolved over the last few decades. Bob offered a number of well-defended, counterintuitive positions, including pointing out the subtle implications of numbered versus bulleted lists. Heeding his message that ordering items in a list creates the impression that a sequence matters when it doesn't, I'll list a few topics Bob covered:
- How the target audience defines the type of documentation needed in ways beyond simply the vocabulary used
- The potential role — and pitfalls — of image, audio, and video media in documentation
- Keeping documentation in sync with products
- The challenges of maintaining, updating, and versioning documentation
- Modern tools for creating documentation
- Bridging the gap between software developer language and software user language
As part of the Katana Graph employee spotlight series, we reached Bob after this mostly technical interview to learn more about the other sides of his work and life.
In your interview you indicated your fondness for George Orwell’s Politics and the English Language. I’ve heard criticism of the tech world that would take that even farther — into the realm of 1984, where the structure of language renders truly independent thought impossible by depriving people of words needed to form ideas other than those of the dominant paradigm. Given your interest and language – and avoidance of the word “functionality,” I’m interested to hear any other thoughts you have on technospeak.
Bob DuCharme: It’s often just a matter of people using new words that they don’t completely understand to sound hip, marketable, or on the cutting edge of technology. The over-use of these words dilutes the words’ meaning until they mean very little, like with “bandwidth” and “agile.” I remember when object-oriented development first got hot and people were using the expression to describe anything with an icon-based interface and saying "look! You treat everything as an object! It’s object-oriented!"
Follow-up: In the area of technology where we operate, we are very tempted to refer to actionable insights and holistic approaches because these seem to be efficient means of communicating. But they’re incredibly tired expressions. Your thoughts?
BD: When a reader sees that someone was writing on autopilot by just churning out clichéed phrases, that reader will go on autopilot as well and just skim without paying much attention. For example, I’ve often said that the value of metadata is that it helps you get more value from your data; if I said that it helped to get more actionable insights from your data, these extra syllables not only don’t add to the meaning — as Orwell explains, they actually take away from it.
How did you end up at Katana Graph? I can see a rough trajectory from W3C standards such as XML and RDF to SPARQL to graphs to a broader scope of graph technology.
BD: I had been working with and writing about RDF and its query language SPARQL for several years and also doing end-user documentation about software products. The Katana Graph platform models data as labeled property graphs, which is a little different from RDF, but they both still use graphs, which provide much more flexibility than the normalized relational tables where most organizations have stored their data for decades. This flexibility enables new kinds of data integration, and Katana Graph brings speed and scalability to this approach that lets customers perform sophisticated modern analytics on datasets that may have been too large and cumbersome for that kind of treatment before. It’s a lot of fun to help connect people with this technology that lets them do cool new things with their data.
Your "Two-Part Invention" performed by the University of Virginia Fall 2020 New Music Ensemble is a very nice little piece. It reminds me a bit of Penderecki or Henry Cowell’s chromatic music for winds, or perhaps the rock group Henry Cow’s famous “Ruins”. Where did that come from and where might it be going?
BD: Thanks! I live in Charlottesville, Virginia, and as Katana Graph’s Austin-based employees know, living in a city with a major university provides a lot of benefits. A wide range of music is part of that, and this particular experimental group is open to community members who have no direct university affiliation. And, when you bring them an idea for a music piece that isn’t completely notated dots on paper, they’re happy to play it, and it is so much fun to bring them some strange idea and then hear how it sounds played by an ensemble.
What instrument do you play in the ensemble?
BD: I've been working on the viola for about five years. When I was young and living in New York City I played loud rock guitar, and after I moved to Charlottesville in 2003 I started on the upright bass and eventually became part of the minor league level of the local jazz scene.
It has been very interesting to see how many different instruments Katana Graph employees play. Someday when we're all in Austin I hope we can all play together.
Commas inside the quotes?
BD: When punctuation is adjacent to quotation marks, the American style is to put the punctuation inside the quotes, “like this,” and the British style puts it outside, “like this”. I tend to use the American style (just like I don’t spell “color” with a “u”) if I know that it will be mostly Americans reading it.
Tech writing adds a twist to this because you’re often writing about very specific character strings. If I tell you that your password is “hello123,” you shouldn’t have to wonder whether the comma is part of the password, so I would put it outside of the quotation marks in that case.