Warning: "continue" targeting switch is equivalent to "break". Did you mean to use "continue 2"? in /homepages/30/d88601657/htdocs/techright/blog/wp-content/plugins/social-networks-auto-poster-facebook-twitter-g/inc/nxs_functions_engine.php on line 169

Warning: "continue" targeting switch is equivalent to "break". Did you mean to use "continue 2"? in /homepages/30/d88601657/htdocs/techright/blog/wp-content/plugins/social-networks-auto-poster-facebook-twitter-g/inc/nxs_functions_engine.php on line 176
Tech-Right Documentation Blog | The blog part of Tech-Right Documentation

How the End of Net Neutrality Will Feel

No Comments on How the End of Net Neutrality Will Feel

May 5, 2014 at 9:52 amCategory:Uncategorized

I went to a gaming convention this weekend. One of the questions I got asked was if I needed WiFi. Crazy question, I mean who doesn’t need WiFi, but all I said was yes.

So I got given a little slip of paper with credentials on it, and went to my room, and unpacked, and fired up my tablet. And I connected, checked some emails, and then I wasn’t connected.

I looked at the available networks and saw there was one with the base network name, but with my floor appended to it. Well, I said to myself, they’ve put in boosters on certain floors, so I should connect to this one instead.

So I did. For a bit. Then it dropped connection again.

This was the pattern all weekend. While sleeping, it picked up emails and notifications fine, but during the day? Forget about it.

Except, the one time I went to the hotel bar for a couple of pints. Then the connection worked flawlessly.

I hope this has helped you understand what the loss of net neutrality will feel like.

My Adventures in DITA, part 3

No Comments on My Adventures in DITA, part 3

January 21, 2014 at 12:00 pmCategory:Technology

Long time since the last update. Life got in the way. But hey, I promise to refund all money you paid me personally for reading my blog.

I sort of forgot to explain why would people care about another unfamiliar acronym in the tech world. So let me do that now, before carrying on. After all, the business side has to be convinced that a technology is worthwhile before they agree to spend money on it, right?

DITA offers a lot of benefits. I will just highlight the ones that are attractive to me.

  • Control of layout and format.
    If you have a pubs department with a bunch of FrameMaker or Word templates, that is great. But unless you have some really esoteric things going on with these templates, individual content creators can always decide that something in the template looks stupid, and that you should be able to list seventeen tasks in a row with a mix of bullets and numbers in the task items, and you don’t need to explain why you are doing each task, because it is so OBVIOUS.
    DITA, based on XML, enforces structured authoring strongly. You can’t get usable output out of it unless you conform to the template set up by your template controller. You can’t not describe what a task does. You can’t put pictures on the title page. And so on. And so on.
  • Single sourcing.
    Write once, reuse in multiple places. Your text can be marked up to only be published to a certain stream (PDF, online), or to only a certain business purpose (marketing versus help manual overview). This saves a lot of time when you are updating existing text. There aren’t five or six documents floating around out there, there are one or (at most) two.

There are other ways to get this. FrameMaker has its structured authoring environment, and some limited DITA support. Other tools also allow you to edit and create single source material (e.g. AuthorIT, Madcap Flare, RoboHelp). But these all cost money.

DITA, at least to install to play around with, is very low cost. Download it. Download and install the JDK. Start playing around.

At the enterprise level, of course, nothing is free, not even open source software. The question of whether implementing DITA versus buying something off the shelf is not something I am going to directly cover here, but I will infer it as I go through the mechanics of getting DITA running.

Board Game Marathon, November 2-3, 2013

No Comments on Board Game Marathon, November 2-3, 2013

November 11, 2013 at 8:22 amCategory:Personal Post

(First of all, my USB card reader decided to stop working, so I don’t have any photos to upload here from the event. I am working on fixing this.)

Pre-game Events

Bright and early Saturday morning (hey, 8:45 a.m. on a Saturday is bright and early), I got to the condo where we would be playing. I got buzzed in by the concierge. While I was fumbling around on my smartphone trying to load the Facebook entry with all the correct data, the concierge said, “You’re going to <number>, right?”

That was indeed a familiar sounding number, so I said yes. As I walked away, he asked, “What is going on up there?”

“Oh, we’re playing board games. For charity.”

I went up to the suite, knocked, and went in. There was a pile of food on the kitchen island, and some gamers. The organizer had some people help set up some tables and chairs, and then by 9 a.m. everyone was there.

Games were organised by having two or three people pick their name from a bag, and then those people would choose the game they wanted to play, and then other people would join in whatever game they wanted to play. As part of prepping for the event, the organisers wrote everyone’s name down on  a meeple and used those as tokens in the grab bag.

What is a meeple, if you don’t know? The little yellow guy a third of the way down here is a prime example.

The Games

So for the next 25 hours, I would be playing a bunch of games. I wrote down the start and finish times for each. When I was more awake, I added some notes.

Battlestar Galactica

Yes, based on the popular television series. Everyone is either a human or a cylon at the start, then things happen, then something called the sleeper phase happens and people who were human for the first bit of the game might find themselves becoming a cylon. The humans are trying to get Galactica to their destination, the cylons are trying to stop them from doing so.

As you might be able to tell from the above, I know next to nothing about the show. People were concerned that I might get some spoilers from playing the game and I was all like, “Nah, I’m good.” Spoilers about the TV show from playing a game. That’s right. That’s how detailed the character cards are.

Anyhow, I was some guy who I only remember now as “Hot Dog”, which involved me flying a Viper around and shooting at things. Every character has different skills, and abilities, and once a turn powers, and once a game powers. Challenges come up, and people throw in skill cards from their hands to try and beat the challenge toughness number.

The trick is, of course, that sneaky cylons can throw in negative or useless skill cards to try and sabotage the process. If the humans pass the challenge, good things (or nothing, which is good) happen, if they fail, some sort of minor to major catastrophe.

I was a human the whole game. The Admiral and one of the others turned out to be the cylons. We fought a mad battle with cylon raiders, a cylon dreadnought robot thing that I managed to shoot and destroy, and at the end it came down to two skill check cards. The first one wiped out all cylons around the Galactica, and the second one (which we failed)  meant that the cylon ships that had been brought back (the cylon ships never go away for good) managed to blow up some of the civilian ships around the main ship and reduced the human population to zero.

Time played: 9:28 a.m.-12:52 p.m.

Terra Mystica

From the dramatic previous game, with its cylon ships and little photos of humans running around the stations on the Galactica, I went to a mystic land where different fantasy type races were trying to colonize and expand their colonies to larger cities. This was my first time playing this, but I had heard a lot of good things about it, so I was eager to try it.

So were three other people, and with the game chooser, this made five. “I’ve never played a five player game of Terra Mystica before,” the chooser said. He did a great job of teaching the game to us, and off we went.

I was playing the Engineers, which basically meant I could build buildings and bridges for a lot cheaper. In balance, I had fewer workers.

I had no idea what I was doing, and the final score showed it. Still a great game, though, and I wound up buying a copy last Saturday.

Time played: 1:09 p.m. – 5;09 p.m.

Dinner Break

You know. Dinner.

City of Remnants

This was one of the games I had brought, and I chose it when my name was pulled from the meeple bag.

In City of Remnants, you have a gang of aliens which have been dumped on this crappy prison planet by the conquering aliens, the Yugai. Your alien gang wants to be the best gang, so you start building shady enterprises and fighting other gangs to try and get the most renown.

I got attacked hard by one of the other players early in the game and spent the rest of the game trying to rebuild my gang. The one who attacked me won, mostly because I didn’t attack him back and the other player attacked a couple of times. He did have a few problems, though, because once a turn the Yugai drop down, and if they land on you, you have to fight or bribe them. And they were mostly dropping down on him.

Fun game, though, and one of my favourites. (Obviously, or I wouldn’t have brought it.)

Time played: 6:15 p.m..-8:44 p.m.


Game times don’t end conveniently sometimes, and two of us wound up playing this game until everyone else had finished their games.

This is a fun little game where you fight over Greek cities with your Greek heroes, beasts, and oracles, to try and perform heroic feats and finally beat your brother (yes, you are battling each other as brothers in this game) by getting that last feat.

I have a copy, but have not played a lot. So, the other guy steamrolled me.

Time played: 9:15 p.m.-9:44 p.m.

Thurn and Taxis

A game based upon building the first postal mail system in Germany.

It sounds dull, but it’s actually very interesting, as you try to build the longest routes, the route that passes through all the provinces in a region, and so on. Not too complex, so the three of us wound up playing two games.

Time played: 10:00 p.m..-11:19 p.m. Score: me 10, the others 19 and 9.

Time played: 11:25 p.m..-12:21 p.m. Score: me 13, the others 26 and 22.

You might note I haven’t won a game yet. Spoiler alert: I don’t ever.


My name is drawn again from the meeple bag, and I pick my second game I brought, Goa. This is probably my favourite game in my collection of its type (the Euro).

I get to teach two people who have never played, and refresh the memory of one who has played before.

Basically you are trying to build a colony on Goa to be the best colony there is. This is all highly abstract, but it does feel like you are doing it.

Final score, me 35, the others 42, 36, and 33.

Time played: 1:00 a.m..-3:30 a.m.


My first time playing, but I’d heard good things, etc. etc.

You are some sort of wizard in a contest to determine who the best wizard is. Through careful use of cards you pick from a pregame draft and dice you pick from a common pool each turn, you try and maximize your energy. Which is to say, points.

I had no idea what the cards did, and people who did were able to build powerhouses that were getting them all kinds of points every turn. A fun game, but not one I’m ever likely to buy.

Final score, me 73, others 209, 184, 150.

Time played: 3:39 a.m..-5:54 a.m.

DC Comics Deck Building Game

That is the actual name of the game, by the way, not the result of me taking notes at 6 in the morning. The publisher didn’t work very hard at all on the title.

This wasn’t a very complex game, which is good at 6 in the morning. It also seems to suffer from a runaway leader problem, because once someone gets a really good card in their deck, there’s nothing you can do to get it out of their deck.

Final score, me 11, others lots more. (My notes are almost non-existent at this point.)

Time played: 6:25 a.m..-7:03 a.m.

Bamboleo Tournament

At this point, peoples’ brains were fried, so we had a Bamboleo tournament until the end. Bamboleo is a game where a huge wooden disk on a pillar has smaller wooden shapes on top of it, and players alternate taking pieces off until the huge wooden disk overbalances and everything falls over.

Chaotic fun. I lied when I said I didn’t win anything, because I did win two games of this before being defeated the third time.

Pass the Potato

You know Hot Potato. We passed around a wrapped prize. When the music stopped, we unwrapped a layer.

There were a lot of layers, but finally the last one was reached. And someone else got the prize. The prize being a game of mini Jenga.

Post Game

People hung around, chatted. One of the player’s wives brought their two children over when picking him up. I made the baby smile by waving at it as mom was heading out, so I actually won another game.

Then people were starting another game of Battlestar Galactica, at which point I decided it was a good time to get out. I said my goodbyes and headed home.

One of my favourite indie coffee places in town was just around the corner. I got a snack and a coffee, sat down, and suddenly the fatigue hit. I finished up and headed home for a few hours sleep.

My Adventures in DITA, part 2

No Comments on My Adventures in DITA, part 2

October 27, 2013 at 11:19 amCategory:Technology | Writing

With the DITA Open Source working at the level I need it, for now, I need to go in and figure out how DITA is structured at a high level.

(I say “for now” because experience has taught me that base configurations never do what you want them to do when you get some experience in the system under examination.)

People will tell you that DITA is just XML, so it’s simple.

<?xml version="1.0" encoding="UTF-8" ?>

<title text="Hi there this is XML!/>

<para>Golly, XML is easy!</para>

That is easy XML. DITA is a wee bit more complex than that, as it is a full-fledged publishing system. Incoporating multiple XML files, multiple transform types, topic maps, other maps, this and that…honestly, I know very little about it, beyond the fact that it’s not easy.

Even if you buy some kind of tool that is supposed to make DITA authoring simple, the fact is that someone in a place using that tool will, from the start, need to understand the possible ways you can build and extend a DITA architecture.

So, as I go through it myself, I will blog my adventures in DITA.

My Adventures in DITA, part 1

1 Comment on My Adventures in DITA, part 1

October 24, 2013 at 1:08 pmCategory:Technology | Writing

So after a presentation by Tim Grantham this week on his new InPrint solution, I thought it was time to look at DITA again.

Since my budget for new software comes solely from sweat equity, the Open Toolkit was the only choice. I will worry about an editor later.

The first test of DITA Open Toolkit is whether you can find the documentation. I didn’t find this process intuitive or helped by the README, but by clicking enough I found the XHTML help file.

The second test of DITA Open Toolkit is how well you know Java. Upon trying to build the demo output, I got a cryptic error message in the DOS shell. Upon thinking, I realised that of course I need a JDK.

After trying again to build the output, I realised I needed to edit the provided DOS batch file to tell it where to find the JDK bin directory.

This accomplished, the output built. Even though I added the JDK CLASSPATH to the startup batch file, Ant is still looking in my JRE for tools.jar.

So, not perfect, not intuitive or well documented, but it works. Now to find a free editor and get to work learning  DITA authoring.


No Comments on Testing

September 17, 2012 at 9:46 amCategory:Personal Post

Is this thing on?

What I’ve Learned From the Startup World

No Comments on What I’ve Learned From the Startup World

February 1, 2012 at 10:44 amCategory:Career

I like attending the various startup social meetings around town. Even though there is very little…ok, there is NO demand for a technical writer in the startup world.

What I like about it is that I see a set of people who are fabulously commited to an idea and distributing that idea to the public in the hopes of making a living. They are putting everything out there because they believe in what they are doing, and they are very positive about the whole experience.

At least, they are in public.

I’ve discovered that I really don’t like button-down places where everything is being done to SuperCorp Runbook 10.2.a.1. I need some variety in my work life, and some interesting stuff to do.

So I’m going to take a page from the startup mentality and do interesting stuff even if it means doing it outside of “normal” working hours. Because everyone needs self-fulfillment in their careers. Because it’s a huge chunk of your life spent making a living, so if you’re not enjoying it, well, there’s not much point.

Long Time No Write

No Comments on Long Time No Write

February 1, 2012 at 10:35 amCategory:Personal Post

September 2011? Really? That’s my last blog entry?

Well, I’ll have to pull my socks up in 2012.

Linked In Etiquette

No Comments on Linked In Etiquette

September 21, 2011 at 11:02 pmCategory:Personal Post | Social Media

It’s always interesting figuring out who to grant requests to connect from on Linked In. I don’t even know if it makes much of a difference, it doesn’t seem to be like Facebook or Google+ where there is at least the illusion of personal data segmentation. So does one just blindly accept every connect request?

Of course not. The skill here, like in real life, is learning the rules of the social game.

My Favourite Piece of Zen Humour

No Comments on My Favourite Piece of Zen Humour

July 4, 2011 at 11:02 amCategory:Personal Post

There was once a man who was crossing a field and met a tiger. Running away, he came to a great cliff and caught hold of a root and swung over the edge of the cliff. But at the bottom of the cliff was another tiger.
Soon two little mice came along and began to gnaw on the root. The man looked in terror at the tiger below. But then he saw the root was for a strawberry vine, and at the end was a ripe strawberry. He picked the strawberry and ate it. “Ah, how delicious it is,” he said to himself.

It’s a great reminder that you have to keep going and find what joy you can in the middle of any seemingly unforgiving crisis. I love this joke.