Looking for writing-related posts? Check out my new writing blog, www.larrykollar.com!

Thursday, February 28, 2019 No comments

Adventures of a #techcomm Geek: Info Architecture

In this adventure, we find that structure isn’t always structure. And sometimes, the structure jumps up and smacks you to get your attention. More geekiness follows…

Image: openclipart.org
As part of our conversion to DITA at work, I shuffled some things around in the huge manual I work on. I moved a huge wad of reference material into an appendix; other content can easily link to it when needed. But the reshuffling got me to take a look at the reference material.

Managed network devices, like the ones I usually write about for work, usually have a way to message the mothership about various issues. Examples include:

  • Hi, I’m online.
  • The power’s out here. I’m running on my battery.
  • Here’s some stats from the last connection.
  • One of my components just failed!

The messages aren’t that chatty, of course, and they often include some variable data. Some are more urgent than others, and might require some action by the network operators.

I had separate topics describing each message, and they came out of the conversion tool as concept topics—a lot more generic than I wanted. As I was trying to get everything done at once, I didn’t give it too much thought. Since the messages were reference material, they would be fine as references. I split them into sections (format, severity, cause, action), and moved on.

DITA to the rescue? Um… nope.

Later on, I came back to the messages. “There has to be a better way,” I thought. After all, the sections could get out of order, or end up with different titles—there’s all sorts of ways to be inconsistent with reference topics. My next thought was, “Hey, DITA has hundreds of elements, and its prime purpose is software documentation. There's probably an entire message domain waiting for me.”

In reality, there are three message-related elements in the entire ocean of DITA, and two of them are inline (<msgph> and <msgnum>). The third is <msgblock>, for tagging message output.

Ah, the joys of information architecture. Creating a message domain from scratch was a possibility, but would likely be a hard sell to the co-workers.

We’re in trouble(shooting) now

I gave a moment to the idea of using troubleshooting topics—then it hit me. A message has a condition (the message itself), a cause (why it was logged), and a solution (what to do about it). That’s exactly the structure of a troubleshooting topic!

The only sticky point was where to document the message format, and I quickly decided that was part of the condition. I used @outputclass="message" to tag the topics, and to have the transform use Format: instead of Condition: for the condition part. I converted a few to troubleshooting topics, and it worked as well as it seemed it would.

On to the next thing

Then yesterday, I got a meeting invite with an attachment, a follow-up to a discussion a few of us had last week. One of the groups in our far-flung department uses InDesign to produce actual printed deliverables (how quaint!). The fun part is, the page size is about 4 inches square—so it’s not a matter of tweaking our transform plugin; we need a whole new one.

But when I started looking at it, the structure almost leaped off the screen, despite a couple of misplaced pages. Each chapter contained a single task, and each step used one page for substeps and graphics. Having that revelation made the call go a lot faster and more smoothly, because it was one of those things that are obvious once you see it. I just happened to be the first one to see it.

So I did a conversion dance, involving lots of pixie dust: PDF → Word, then Pandoc converted that to Markdown. After some serious cleanup (and moving misplaced content where it belonged), I used a couple of scripts to break the Markdown file into topics and create a bookmap. DITA-OT gobbled up the bookmap and Markdown topics, and spit out DITA topics. Thus, I had a pilot book we can use as test data for the transform.

The InDesign users also have a couple more formats; one is close enough to a regular book that we’ll have them use the standard transform. The other is a folded four-panel sheet… that one is going to be interesting. I’m going to have to resist the temptation of blowing off documentation work for glorious coding.

Stay writing… until I geek again.

Tuesday, February 26, 2019 No comments

A weekend at Camp Driveway

It has been a wet winter so far. We’re currently getting a few days of dry (and reasonably nice, for late February) weather… in mid-week, of course, when we’re all working or at school. But a couple weekends ago, we had a mostly dry weekend—that is, the rain didn’t arrive until Sunday afternoon. It was seasonably cold—around 50°F for highs, not quite freezing for lows.

Roughing it in style
If you ever end up with a popup camper, Popup Portal is a deep hive mind that can tell you pretty much everything from the most basic tips to walking through complete rebuilds. Now the Starflyer (I can’t improve on the name that Starcraft gave it) doesn’t need anything close to a complete rebuild, but there are a few maintenance issues that the previous owner (and perhaps those who came before) neglected. The Portal has been very helpful in that regard.

One thing the hive mind recommends for new popup owners is to do what they call “Camp Driveway.” In other words, set up the camper in your driveway or back yard, and spend the weekend in it. You get to test it out, and figure out what you need before you go “live.” Mason was wanting to try out the new camper, so I opened it up and Camp Driveway was on!

Fortunately, I’d ordered a bunch of accessories from Amazon—an extension cord, an adapter to plug an RV into a house outlet, leveler, heater, 12V LED bulbs (they’re brighter and draw less power, important if you’re using a battery for lighting) and a few repair and maintenance things. I was pleased to find that everything worked as intended. The interior lights did a fine job of illuminating the camper, the stove fired up once the air got worked out of the lines, the outlets were happy to charge my phone and Mason’s tablet (and keep a night light glowing). The “Little Buddy” heater, which uses the same small propane cylinders as lanterns, was a big help because the electric space heater that came with the camper wasn’t too helpful. With both heaters going, the digital thermometer I brought along inched up to about 67°F at tabletop level (not nearly as warm along the floor, though!). But still, with the beds a little higher yet, I figured that was going to be just fine. Besides, we had the same sleeping bags we used for Mason’s Polar Bear Camping outing a couple years ago. If we kept warm enough in an unheated tent, a popup with (some) heat would be at least as warm.

It was. My first night was restless, with the electric heater kicking on and off every 15 seconds or so, but I stayed warm enough. Mason, wrapped up in the down mummy bag, had no trouble sleeping at all. For us old farts, I think we’ll need a memory foam topper on our bed. The camper came with a literal Porta-Potti, a little self-contained toilet that sits in a cabinet during the day and Only Comes Out At Night. It turned out to be very handy—after I turned off the Little Buddy at bedtime, the temps inside the camper dropped to around 55°F, but that was still better than the 34°F outside. Especially if you had a post-midnight necessity.

In the morning, putting a kettle on the stove and cooking bacon&eggs helped to warm things up. The French press I bought myself for my birthday finally got its first run, and there’s nothing like a good strong cup of coffee on a cold morning. The Starflyer has fairly primitive plumbing—a hand pump at the sink, and no hot water heater—but the Popup Portal hive mind had a solution for that. Get a pump pot, fill it from the kettle in the morning, and you’ll have hot water to wash the evening dishes (and an afternoon coffee, if necessary). Actually, we used bottled water, since I’d put RV antifreeze in the water system to prevent serious issues until spring.

The second night went better for me; I turned around to put my head toward the center of the camper, and for some reason I found that more comfortable. I left the Buddy Heater going until it emptied its canister, which saved me the hassle of getting up and turning it off. It went a little longer than I expected, which is nice. We got to air out the bacon smell for a few hours, and I folded up the Starflyer as the first sprinkles came in mid-afternoon.

Camp Driveway was a success. I came out with a list of stuff we need, and am holding out some hopes of hitting a local campground next month when Mason has another no-school Friday. A 3-1/2 day weekend would be a nice warmup to our Spring Break trip to Mom’s…


Related Posts Plugin for WordPress, Blogger...