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…

Wednesday, January 02, 2019 No comments

Campy New Year!

I think a lot of us are relieved to see 2018 in the rear-view, and perhaps are directing a forest of Meaty Middle Fingers its way. But it had its moments. Charlie’s continuing to learn new signs, even if he isn’t speaking out loud yet, and is starting to put two-word sentences together (often things like “eat sandwich”). At any rate, the year ended well.

I’ve been looking for a popup camper for the last couple months. The wife is on board—she won’t tent-camp, but she actually encouraged me to buy a (far smaller and less-equipped) popup some years back. The money didn’t shake out then, but a couple months ago I had a surprise moneybomb—the workplace is being acquired, and I’d had a standing order to sell some stock if it hit $30. So, all of a sudden, the hunt was on. I set a budget, found Pop-up Portal, and started learning all I could from a deep hive mind.

Searching Craigslist, I immediately found one local to me; it was 20 years old, but solid and a lot roomier than I remembered them being when the parents rented one (the slide-out dinette probably had a lot to do with that). The price was well within my budget.

There were snags, though, and it was probably all for the best. I thought I’d set up a transfer from the broker to my checking, but I hadn’t, and doing the setup (of course) took longer than I wanted it to. I was annoyed with myself, because I felt like I was stringing the seller along, and told them to go ahead and sell it if someone else came by with cash in hand. Meanwhile, I used the time to research what I could. Good thing: turned out our vehicle can pull 2000 lbs, and the camper weighed in at 2600. That wouldn’t have ended well.

Off to Craigslist again. This time, I had a specific set of criteria. Absolute requirements: 1800 lb or less, A/C (Planet Georgia summers can be horrid without it), camp-ready. Nice to haves: 1600 lb or less, a toilet, full 12V setup. The latter is not a given; all the sellers I talked to always camp at places with full hookups and don’t have battery power hooked in.

After tossing obvious scams, newer campers that were way over budget, and big amenity-laden models that blew away my weight allowance, I ran out of local options. Expanding my search radius turned up a promising find that checked all my “must” and “want” boxes, but it sold before I had a chance to go look at it. Another one turned out to be a scam (“I sent it to an eBay dealer in Omaha who will deliver it for free”)… yeah, right. I reported that one to the FTC. There were a couple of promising leads in Alabama and South Carolina, but the logistics (especially around the holidays) and the weather just wouldn’t cooperate. I decided to give it a week and see what happened next, and seriously considered upping my budget.

So Friday, a new listing, um… popped up. It was slightly over budget, but I thought “hey, that map looks familiar.” Turned out it was local! I called to check it out on Saturday, and the seller said “I thought that listing went away. But I’m on my way over to the storage unit now, we can meet there.” It was, like many of the days have been around here, rainy and crappy, but we did crank up the top so I could have a look at the not-actually-canvas (it’s called Aqualon™). It was intact, if slightly grimy.

He said, “the rain is supposed to let up tomorrow, why don’t I bring it over to your place and we can set it up?” Sounded great by me, especially since our car has a hitch but no wiring just yet.

So here he came, in a gigantic diesel 4-door pickup (white, imagine that), big enough to pull a gooseneck trailer, with a 1500-ish pound popup behind. I doubt the truck even felt it. Negotiating our horrid driveway involved him rolling his front wheels onto the grass, which dug some pretty deep divots. Couldn’t be helped. We unhooked and pushed it in front of my Miata, then commenced to setting it all up.

It was less grimy inside than out, except for the floor and ceiling. The upholstery is intact, and there’s already an outdoor rug—one less thing to get. There’s also a space heater and a case and a half of bottled water. I worked the hand pump at the sink, and to my surprise water came out. Turned out the 10-gallon water tank had about 3 gallons in it.

2001 Starcraft Starflyer
Long story short, he knocked the price down to exactly my budget, and I cut him a check. We had a break in the rain today, so I spent much of New Year’s Day attacking the ceiling and A/C unit (I don’t think anyone ever cleaned those filters) with disinfectant wipes while Mason cleaned up the beds with a Dirt Devil.

The dining table is the size it is, because it doubles as a spare bed (spanning the dinette benches), but it makes things a little tight. I’d like to include something narrower for our trips. There are a few minor repair items to address as well, but it’s supposed to be sunny this weekend. Mason is already wanting to set up and sleep in it. Charlie likes clambering around in the bunk ends as well.

I’ve got it folded up for now, because I needed to get the Miata out of the garage tomorrow. Still some cleaning to do—mainly the cabinets on one side, vacuuming under the seating area, and scrubbing the floor. I’m going to have to graft in a battery system, because a couple places I want to take it don’t have hookups. Holiday’s over, but we’ll have a few of our own holidays in the months to come. Sooner than later, I plan to clean up the other side of the detached garage so it has a dry place to live.

For the future, we may do some remodeling. I’m looking over Pop-up Princess for ideas. For now, I’m digging on the geeky model name, “Starflyer.” Not only did it come with a name, the shelf in the king-bed front bunk is called a “Space Station.” I added a bunch of accessories to my Amazon wish list, as much to remind me what to get as anything else.

So we should have some new vacation destinations in 2019. I’ll be glad to share. Maybe I won’t have to burn off a bunch of vacation time at the end of each year…

Wednesday, December 12, 2018 No comments

Adventures of a #techcomm Geek: Blurrier Image

In today’s installment of Life of a #techcomm Geek, we return to a subject that draws this geek like a moth to flame: file conversions. Hazardous, yet compelling. Lots of geeky stuff follows…


I’ve had this particular line in my Tines to-do list for a while. As part of our transition to a new documentation system, I and another writer handled the conversions. We had a high-end tool to help us out, although creating rules was a dicey proposition and the vendor ended up helping (we made tweaks where they could make an obvious difference, though).

In the most recent round, we got to the FrameMaker-based docs. Frame (as its users often nickname it) is unique in that it allows overlaying callouts and other graphic elements on top of images. This is a huge help for translating manuals, because the writers don’t have to maintain a separate set of graphics for each language. Anyway, since the new system isn’t FrameMaker, something else had to happen. The conversion system could be configured to either flatten the images (convert to a PNG, rasterizing the callouts) or create an SVG (Structured Vector Graphics). We chose the latter, thinking that since SVG is an XML format, the new system could maintain them easily.

We were wrong.

Long story shortened considerably, we eventually threw up our hands and decided to convert all the SVGs to “flattened” PNG files. The writers would keep the SVG files on their hard drives to make changes, then upload a new flattened PNG when needed. I wrote a script to do the deed; it crunched through hundreds of SVGs at about one per second, and updated all the links in the book to point to the new PNGs.

All well and good, until one of the writers went to publish. “The images look blurry,” she told me. Taking a look, she was obviously right. It took me about three seconds to figure out why.

You see, our SVG files have a width attribute, which was set to the width in the original FrameMaker files (a typical width is 576 pixels, which at 96dpi is 6 inches even). All well and good, but the original images run about 1200 pixels wide—so in essence, we were throwing away over ¾ of the image data when doing the conversion. No wonder it looked blurry! But we were all weary of messing with it by that point; I had written scripts that:

  • extracted embedded images from an SVG, converted them to PNG, then changed the link so the SVG referred to the file instead
  • went the other way, embedding images in an SVG
  • converted the entire mess to PNG in one swell fwoop

The documentation work that was my primary job function had been back-burner’ed for too long. I added an “investigate this further” item to my backlog list and got back to the bread-and-butter part of my job.

This week, I all but cleared a fairly long to-do list in three days, so I thought maybe I could give this thing another shot. A quick Google turned up some promising code on superuser.com; I divided the image width by the scaled-down width in one SVG, applied the script, and got a nice sharp image! The only problem with that is, it would take about 10 minutes to do each file by hand, and there are hundreds. A script is the only practical way to blast through all of them.

When I tackle a situation like this, I tend to use a shell script to drive awk, Perl, and XSLT scripts. Each has its strengths, and trying to force (say) XSLT to work some of awk or Perl’s string-processing magic is more trouble than it’s worth. And vice versa. So… XSLT to extract the file name and (scaled) width, awk to parse the output of file (a utility that returns the dimensions of an image file) and do the calculations, all wrapped up in a shell script to conduct the Geek Orchestra.

Of course, I ran out of time this afternoon to put the whole thing together, but I have all the sub-script logic down. I just need to score the symphony. That will likely take me to noon tomorrow, then I’ll be back to bugging people already bogged down with too much stuff to lend me their expertise.

I also achieved Inbox Zero at work today… and that’s a rant for another time.

Friday, December 07, 2018 2 comments

A TB02 of sorts…

A long time ago, back when The Boy had more than his share of teen angst to deal with, I had a series of “TB” error codes. TB02 was “He moved back home (again).” (Dang… this blog is old. 13 in Internet years is like “going out for lunch meant we hunted wild tacos with spears.”)

Fast-forward to now. He’s married, living in his own house, starting a business, and doing a decent job of adulting. Unfortunately, he ended up with some health issues that put him in the hospital for the better part of two weeks (not his foot this time). During that time, his wife & his mom got together and really kept things going, spending days and nights with him, making sure he was being taken care of—I was thrilled at how well they worked together. Still, he was bored $#¡+less, and was more than ready to get outta there and get back to his life.

Yesterday, they sprung him, but with a condition: he can’t be left by himself for a week. The daughter in law has to work (hey, I totally understand, because I do too)—so he’s here at FAR Manor. He’s not really moving back in, just hanging out with us for a week, so it’s not a real TB02. I’m sure Mason is happy to have him around, because he was supposed to stay with his dad for a few days Thanksgiving week, but with one thing or another, I haven’t gotten home before Mason was asleep in bed.

Yeah, The Boy missed Thanksgiving, but I think we’re going to have an extra dinner this weekend. After all, we really have something to be thankful for this time.

Wednesday, December 05, 2018 No comments

When you go to the delicatessen store…

I’m one of those people who like liverwurst. Always have. I gave it up for a while, what with the weight gain and high blood pressure, but Boar’s Head came out with a lite version the has lots less fat and sodium, and is still pretty tasty.

A few weeks ago, I got a quarter pound. As the deli guy was slicing it up, I thought, “Hey, Charlie likes food with this texture. I wonder if he’d like this.” So the next evening, I made him a sandwich and offered the corner.

NOM!
Charlie likes sandwiches okay. But when he got a taste of this, he grabbed it out of my hand and gobbled it down. Now up to this point, whenever he got hold of a sandwich, he would open it up, remove the meat, and eat the bread. Not this time, or any time since! The experiment was a roaring success, and I might have got one sandwich out of the batch.

So I found myself at the grocery store a few days later. I got half a pound this time, figuring maybe I could sneak a sandwich or two for myself. I came home and told the wife I got Charlie and me some liverwurst. Charlie heard this, and pushed me into the kitchen. “It doesn’t matter if I just ate or not, I want some of that good stuff!” Next time, Charlie was with me, and he got the sample slice (plus a slice of beef bologna, which he also liked pretty well).

Once again, we were out. I picked up Charlie from daycare on the way home from work this evening, and decided to grab a whole pound this time (because I still only get two sandwiches out of a half pound after Charlie gets through with it). We headed toward the deli, and he pointed and hooted, remembering how he’d scored a freebie last time. Once again, he got the sample. He finished it while they were slicing the cheese, and he signed “more.” Sure, why not? A couple pieces of liverwurst won’t hurt anything.

But he wasn’t through. As I rolled through the store on the way to grab a box of diapers, he wanted another piece. And another. And one more at the checkout. Then, when we got home, he devoured all but two bites of a peanut butter sandwich.

So when you go to the delicatessen store, grab another pound of liverwurst for Charlie and me. What we have now won’t stay around long.

Monday, December 03, 2018 No comments

Mason Minecraft Mondays

Mason took to Minecraft like a natural-born bricklayer. He comes up with some rather interesting constructs from time to time, and we’ve talked for a while about posting some screenshots. Today’s the day…

The aerial view of his seaside croft, built around a waterfall. Left to right: barn, house, garden.



This is the barn at the entrance. Mason tells me the chimney-looking thing on top is decorative. I suppose it makes it easier to spot from out at sea.


Over on the other side of the house is the garden. The stream runs alongside it, leading to the waterfall. This POV is over the stream, looking toward the ocean.


In the house, Mason has a spacious kitchen. His rooms tend to be large, and why not? In real life, it would give him more room to run around flat-out, with Charlie right behind him.


After filling up on pork chops and a variety of fresh veggies, and racing around the place, perhaps a nap is in order. The bedroom is appointed with the necessities. Left to right: computer, bed, storage containers for clothing and such.


Looks like a peaceful place to spend a long vacation to me. When I come back, I’ll bring you some more Mason Minecraft Mondays.

LinkWithin

Related Posts Plugin for WordPress, Blogger...