Category: Writing

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.

Creative Commons

No Comments on Creative Commons

December 18, 2010 at 10:42 amCategory:Writing

I love Creative Commons. Whenever I share anything on the Web, even a set of photos, I always slap a non-commercial CC license on it in plain view. (Well, not with close friends and family. I’m not THAT mean.)

Is it overkill? Let me turn that around and say, don’t you respect the work you do? Don’t you have some pride in it? Do you want someone claiming they never knew it wasn’t public domain?

Copyright is facing a lot of challenges in today’s world. I think Creative Commons is a good step in the direction we need to be heading with law changes around it. And that’s also why I do it, to spread knowledge about it. It’s also why I wrote this blog entry. 🙂

Well, You Think You’re Smart…

No Comments on Well, You Think You’re Smart…

December 3, 2010 at 3:24 pmCategory:Writing

I thought yesterday’s blog entry was topical. Then I saw this.

Curse you, Nikon! 🙂

 /via @arh on Twitter

Tech Writing Old Skool

No Comments on Tech Writing Old Skool

December 2, 2010 at 10:40 pmCategory:Writing

(This is my Christmas present to anyone who remembers using PageMaker for creating docs.)

Hist! Ho! Friends! Do ye long for days of past glory in technical communication? When ye were still called a “technical writer”, not this fancy-dancy “technical communicator” foppery? Said title change being only used to keep raises low?

Those days when you made or broke a product? When vice-presidents saluted when you walked by? When the CEO would stand by your cubicle, digging his toe into the ground, twisting his hat in his hands, but not daring to say a word so as to not interrupt your creative flow while you were finishing up the documentation?

Then, what happened? Everything went bad. Developers and product managers figured out how to build a (mostly) self-documenting interface. Applications got smaller: Web apps and then smart phone apps. As functionality got smaller in scope, so did the need for documentation.

Terror! From the darling of the executive suite, you fell to somewhere just above the janitorial staff. “A cost centre,” they muttered behind you. “Excess fat to be trimmed,” and then they smiled when you spun your chair around in your cubicle and looked at them standing right there. “Something wrong?” they asked. “Did you lose a font?” And then they walked off, arm in arm, laughing, while you in frustration and humiliation ran your spell checker again and again.

Do not despair, friends. Run, do not walk, to the nearest manufacturer of high-end digital SLRs (DSLRs) and apply for a job as their manual writer. Yes, you read that a-right. DSLRs.

The interface is the documentation? There are so many knobs and switch positions and tiny icons on the rather small body. Yes, they do have screens, but what kind of screens? Hint: not big ones. Limited functionality? Your average high-end camera owner wants all the functionality your tiny-fingered elves can cram into those electronics and optics.

So, DSLRs are very popular, and somewhat expensive, and (per above) complicated, which means your average buyer wants a lot of explanatory text in front of them. Which someone (psst, it’s you) needs to create. Your average buyer from anywhere in the world! Hello, localisation! Hello, huge project budget! Is that the CEO I see behind you, digging his toe in the ground and twisting his hat?

Yes, just get a job doing documentation at a DSLR manufacturer, and you will be back at the top of the IT heap. But don’t use PageMaker, they don’t make it anymore.