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.

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

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.

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

Instructions to assemble a spinning wheel

I have only ever documented software.

One of my secret tech writer dreams is to write doco for tangible products. “Congratulations on the purchase of your whipper snipper” I’d write.

Recently I bought a portable spinning wheel that folds up and fits into a carry bag. It is called a Joy and it is aptly named – a marvel of design and engineering.

When the box arrived, I had to assemble the wheel. A very exciting prospect because I like building things and I like reading instructions.

I was keen to play every tech writer’s favourite game of picking the guide to pieces.

20140526-202956-73796446.jpg

Imagine my disappointment when it was actually quite okay!
20140526-202956-73796167.jpg

The critique

It was two column layout. Some of the content ran down the page, some of it across. A trifle confusing but not too bad.

The guide started with a graphic parts list (Ikea style), but should have also included a labelled diagram of the assembled wheel.

20140526-202955-73795908.jpg

Spinning wheel parts have names that may be foreign to new users. Reading instructions like “Thread the flyer spindle into the top shaft…” and “Hold the whorl with one hand…” didn’t bother me, but would have been double-dutch to the new spinner.

Happy and sad faces were used to show the correct tension.

20140526-202953-73793445.jpg

The re-write

One of the opportunities open to job-hunting tech writers is to take a poor example of writing, improve it and then send it back to the source.

I think I’ll take the high road on this one. I really like the Ashford company and their products. Although I could completely redesign their user guide, one could argue that there’s nothing really wrong with it since I managed to assemble the wheel with no problems.

Any anyway, I’d rather be spinning. Look how it folds up  – so cool!

20140526-202952-73792617.jpg