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.

Advertisements

Creative problem solving for tech writers

How much problem solving do you do in your role as a tech writer? I used to do quite a lot. The company I was working at had a start-up mentality and culture. New ideas were encouraged and we usually had little to no budget.

One day the new boss came in and didn’t like our release notes. Apparently they were “too dry and boring”. I took that as a compliment 🙂 It meant we were doing our job—accurately describing the changes in functionality from one version release to the next.

Anyway, we needed to reinvent a lot of things when the new management came in. And that meant we had to think of a lot of new ideas. Which can be hard sometimes.

Tech writers are problem solvers

I never thought of myself as an “ideas man”. But in a short period of time we were re-designing release notes and thinking up new ways to engage with clients to improve our service and value offering.

We had to come up with technical solutions, too, for delivering our content in regional centres.

With no Marketing department at the company, the Tech Comms team had to create launch plans and project comms plan to engage with staff and clients.

So we not only had to improve the look and feel of our content (the word sexy was used), we also had to come up with elegant technical solutions—to reduce maintenance overhead for our team as well as ensure a great experience for users across the globe.

The fun part

Tech writers often work in an orderly and structured way, and can sometimes find creative problem solving difficult.

Here’s my tip: try Zentangle.

Zentangle is a form of meditative doodling. Don’t worry too much about the science but apparently it taps into a part of your brain that helps you zone out, like meditation or yoga. Zentangles are usually quite small – so you don’t have to commit to anything big. It can be addictive and is a really quick way to relax; and at the end you have a piece of artwork!

How-to

Get a bit of paper and a pen. Mark out a shape first (square, circle, whatever) then divide it up and fill in each section with a repetitive design. Sounds simple, but it’s very effective.  And you feel like you’ve made something really cool at the end even though you’ve just been drawing lines and squiggles.

photo 1

When you’re doing it, don’t focus on the problem you’re trying to solve, just enjoy the doodling. You’ll feel pretty chilled out afterward and you’ll find that new ideas will come to you pretty easily. You’ll become a natural problem solver!

Go on, I dare you. If you have to think up 5 ideas by tomorrow, give Zentangle a go.

Creativity begets creativity.

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/

Comma splices and cultural differences

The craft of crochet is fundamentally the same, but the stitch names are different in the UK  and the US. The same stitches have different names. A single crochet (sc) in America is a double crochet (dc) in England. You have to be very aware of the origin of your pattern before you start.

And knitting comes in English and Continental style flavours. The same fundamental concept, just that you hold the yarn and needles differently.

Same same, but different

Regional writing differences

At a previous workplace I worked in a team of writers, one of whom was an American who was travelling through Australia. It constantly surprised me that, although we were very similar in many ways, we were also very different. It was so subtle as to be unnoticeable, but then it would hit you like a sledgehammer when a difference cropped up.

Little things like idioms and slang. I remember a funny day we had to urban-dictionary “tweaking” – who knew it was a drug reference!

One day she was peer-reviewing something I wrote and she sent me this in an email:

splicecommalogotrans3

We had a good laugh about it. I can’t remember the exact sentence but we worked for a software company, so complex, noun-heavy phrases were difficult to avoid.

Go with your gut but remember your audience

I stuck to my guns and said that my spliced comma should stand. Luckily my Aussie colleague backed me up. I was taught in school to use a comma in long sentences where you would naturally take a breath if you were speaking. I have since learned that some Americans are very anti- comma splicing.

I’m not going to debate grammar rules here, but I learnt two things: stand up for what you believe in, and go with your gut (but remember your audience).

My Aussie colleague would confidently tell me that she would often end sentences with a preposition so long as it felt right. Our audience was primarily Australian so these decisions were acceptable.

I have always been of the belief that as a tech writer:

you’re allowed to break the rules so long as you understand what rule you’re breaking

And it’s all about effective communication of information to your audience.

You do what feels natural and it all comes back to your audience, or in the craft sense, what is right for the project.

Takeaways

  • Always peer review – editing is a Good Thing
  • Don’t be sensitive
  • Be open to other ideas of “correctness
  • Remember regional differences
  • Discuss with colleagues, get consensus then be consistent

Unword of the Day

a whole nother
very unique
do the needful
revert
expel the virtues

My husband used to work on a project at a major bank, and he dealt with staff in their many South East Asian offices. Working with lots of people who have English as their second language, he encountered a wide range of unusual language usage.

Being a sensitive soul (and a tech writer in another life, I’m sure) he was often offended by some of the clangers he heard, and would bring them home for me to be shocked about.

Many blog posts have already been written about “irregardless” but that is one of the first he noticed.
“Do the needful” is another favourite, and one he heard the other day was “expel the virtues”.

It’s everywhere

I subscribe to the view that English is a living language and I tend to embrace language inventions that tickle me. I’m all for the reinvention of “because” as a preposition (now because NOUN), and I regularly use fat as the past participle form of fit:

“I tried on the skirt and it fat real good”.

People who are new speakers of English tend to be able to combine pieces in new and interesting ways. In some cases they are just following the language instinct, something Stephen Pinker wrote a whole book about.

The point

It’s not worth losing sleep over. Try to go with the flow and don’t censure people when you think they’ve made a mistake. It may be hard to relinquish the meanings of words like “literally” which has recently had a ‘secondary’ meaning accepted in the dictionary, but this is the way of the future and sometimes I think if you can’t beat ’em, join ’em.

What’s your favourite font?

Some time ago I applied for a tech writing job and part of the application process required me to fill out some questions online. They were standard scenario questions like “Describe a time you had to handle multiple conflicting priorities” but one of the questions was “What’s your favourite font?

This kind of tickled me. Was it a trick question? Separation of form and content is (for some people) an integral part of being a technical writer. We’re not graphic designers, but I believe you do need to have an appreciation for design and how your output is presented to your readers – because this impacts the way it is consumed. Font plays a role here.

Anyway, in my response I decided to cover both bases – saying that tech writers shouldn’t have a favourite, but since you ask… THEN I had to think about some fonts.

Know any good fonts?

As it happened, we had recently given a facelift to the release notes where I was working. We had to scout around for a clean, professional, modern-looking font. Management had told us they really liked the Microsoft Windows 8 release notes, so we went with Segoe UI. For a while, that was my favourite font.

But I also have a preference for Proxima Nova, which is used on the ABC news website and is actually one of the most popular fonts on the web. (I use the Chrome extension WhatFont? to identify fonts on websites.)
So without too much thought, I did actually have two fonts I could talk about to give a credible response in this job application.

Be prepared

The fact that this company included such a question in the recruitment process demonstrated their expectations about what they wanted a tech writer to do. They’re expecting a design element to your skill set. It pays to be prepared. Have a few fonts up your sleeve ready to pull out for just such an occasion.

 

 

Friendly 404 page

I stumbled across a great 404 page the other day over at GitHub. I’m a Star Wars fan so this really tickled me. It’s got the parallax affect too. Kinda cool.

github404

404 pages don’t scare me anymore. I eyeballed the URL, removed an errant character and the page displayed fine. It’s not always that easy.

Friend or foe?

The GitHub 404  isn’t particularly useful, and Chris Morgan explains why in his case study. He makes a good point that really useful 404 pages are computationally expensive.

There are certain things that good 404 pages do. The page can be generic and still be helpful – this scatter/gather post covers it nicely.

Handmade 404

In my last role, our team had to create a custom 404 page and it was a really interesting exercise.

Our 404 page was not for a website but an internal site accessible only to logged-in users of our software.

We knew the page would display if:

  • the user hit a bad link or typed the URL incorrectly
  • the user wasn’t logged in to our software
  • the URL didn’t exist because we hadn’t yet uploaded the content
  • there were network problems on the server side.

Designing this 404 page required finesse and an understanding of multiple disciplines:

  • technology: how the site was hosted, how it was integrated with our software and what the technical reasons were that would cause the page to display.
  • ux: how users were getting to our site, how they were likely to arrive the 404 and what information they would want to see on the page.
  • tech writing: what language to use on the page to acknowledge the problem, and how to convey a clear message about the actions users could take.
  • design: how to layout the page (including placement of the title, paragraph and procedure), and how to style the page to make it consistent with the rest of the site.

The content and the design of the 404 page had to cover a lot, and we wanted to keep it brief.

Rising to the challenge

We used a clear statement at the top of the page acknowledging the problem, along the lines of “We can’t display that page.”

We included a brief, 2 sentence paragraph explaining what happened, and to “try again soon” in case of network or content-loading issues.

Lastly, my colleague crafted a succinct 3 step procedure advising users to “log in to the software then try the link again”.

The page also included contact details for our Helpdesk so users could get further assistance.

The point

Tech writers rule! and if you ever get the chance to write a 404 page I encourage you to do so because they are challenging and fun.