Collaboration in Tech Writing

I love collaborative writing. I think it is sometimes the best way to achieve excellence in a piece of written work.

I had a great manager at a previous workplace and we worked really well together. We’d come up with a thing that needed doing—I would write 80%, she’d review and take it to 95%, then I could take it all the way home. Or I’d do an outline, say 20%, she’d take it in a new direction to 60%. I’d get the flavor and run with it and we’d both get it over the line.

Learn to let go

It works well when you’re not married to your ideas. When you’re just as happy to discard them because you recognize the superiority of someone else’s. Sure, it’s nice when someone recognizes your idea as great, but without constructive criticism how can you ever improve?

A little while ago I helped a friend write a Wikipedia article. We worked on it independently and when I told him I had a draft ready, he let me know that he had a draft of his own. I sent mine through to him and when he published the final page I could clearly see how well our ideas had complemented each other. Some of his sentences were better than mine, but I had pulled in ideas and added references in areas he hadn’t touched on. Together, we’d fleshed out quite a nice little piece. And it felt really gratifying.

Teamwork is empowering

Working in a team of writers is rewarding. It reminds me of a quilting bee – a group of people working on a project, each bringing their own strengths and working toward a common goal.

DITA done for you

Let’s face it: DITA is hard work. There is a steep learning curve and once you get it, you feel like you deserve an “I’ve climbed Everest” t-shirt.drivermanual

A little while ago, I developed an open-source sample DITA project. It is hosted on GitHub and is based on a 1960’s Morris Mini Minor Owner’s manual.

It will suit anyone wanting to explore a real DITA documentation project or anyone with an interest in Minis!


ManualSnippet


What is it?

It’s a complete DITA project, made up of a series of topics and ditamaps which together illustrate the use of many DITA features such as metadata, cross-references, indexes and reuse (through conref and conkeyref).

The project also demonstrates conditional publishing for Morris Mini Saloon and Traveller models, as well as the Austin Countryman (a re-badged Morris Traveller).

What does that mean?

I’ve done the hard work for you! If you are learning DITA and want to see how things are supposed to hang together, take a look at this project and experiment with different output formats and conditions.

You can play around with it and then generate the Mini Owner’s Manual as a PDF, an HTML Help file or whatever you fancy.

HelpOutput

What tools do I need?

I wrote this using Oxygen XML authoring software (with guidance and QA review from Tony Self).  You don’t need to use Oxygen XML to edit the content because DITA is a standard – so any DITA tool is suitable.

DITA_topic

OK, where can I get it?

The project is available for anyone to download from https://github.com/flicstar/DITA-Mini-Manual.

Where can I learn more?

If you are looking to self-learn DITA, check out the training course hosted by Scriptorium, also on Git Hub:

https://github.com/okeefescriptorium/ditatraining.

Another great resource is Tom Johnson’s series of posts about his DITA journey:

http://idratherbewriting.com/2014/04/16/my-dita-journey-begins/

Writing fortunes for cookies

Ever had to write a fortune?

I’m working on a crochet project – a bowl of fortune cookies.

The pattern I’m following stitches them closed and embroiders a smiley face on the outside but I chose to include actual fortunes inside my cookies.

Writing challenge! I knew I wouldn’t have a lot of space or flexibility for presentation of the messages, so brevity was key. I also had to make some style decisions.

Font. Punctuation. Language.

Next, because I was using iron-on transfer paper I needed to print the text backwards. I created mirror text in Word and did a few test prints.

Result

You can’t turn tech writing off, no matter the project.

image4

Lifelines in writing and knitting

Being able to reclaim work is very important as a writer and a crafter.

If you make a mistake in your knitting, you can tink – that is “knit” backwards. Basically you undo stitches one by one by reversing your actions to get back to a point in time. In tech writing terms, a bit like Ctrl+Z.

More drastically you can frog your knitting, which means you take the stitches off the needles and unravel big time, past the point of your mistake. Kind of like restoring from backup: you’re not really sure where you’re going to end up, and it’s probably further back than you’d like.

The most reliable way to recover from a mistake is to use a lifeline. A lifeline is a strand of yarn that you thread through the stitches on the needle and it acts as a place marker. You can confidently return to a known point in time and the stitches won’t unravel past your lifeline. This is as safe as source control.

20140608-095858-35938417.jpg

Tech writing lifeline

Source control is a lifeline in tech writing.

In the lace knit scarf I’m working on, the pattern is made up of 8 repeated rows. Every time I reach a perfectly completed set of 8 rows, I move the lifeline up.

In writing, this is akin to using a source control system to regularly check-in files or label a version of completed work.

Just like the second cup of tea is never as good as the first, I can never quite recapture the perfection of a phrase I have written when I have to reconstruct it from memory.

With source control, you don’t have to recall artful phrases from memory or reconstruct lost work.

Know how it works

Most authoring tools these days integrate with source control software. I recommend that you become familiar with the nuts and bolts of how your source control system behaves.

  • Where are the files actually stored?
  • How does branching and versioning work?
  • How can you retrieve an older version?
  • Does it allow multiple checkouts of the same file? If so, test what happens upon checking-in.

Be aware of the flexibility and limitations of your source control software – it might just save your life.

20140608-095859-35939207.jpgFind out more about fixing your knitting mistakes.