Kate Winslet’s 7 Ways to Checking Technical Documents

Post by Ivan Walsh. Follow me on Twitter.

What can Kate Winslet teach you about proof-reading technical documents? Watch the movie The Reader and it will make sense. If she was writing this blog, she’d probably say: “Don’t do it all at once! One of the biggest mistakes you can make when revising any technical document, is to do it all in one go. You can’t!” And she’d be right.

7 Secret Ways to Revise Technical Documents

 

Make it easy on yourself and focus on one area at a time. Instead of revising the document in one session, break out the tasks and revise the document by task. For example, start with checking the facts, then the spelling, how the document flows, cross-references, footers, index entries and so on.

Seven Ways to Revise Technical Documents.

1. Overview – In the opening section, do you have a statement, a sentence or two that states the main point or argument of your document? Likewise, is there a conclusion that ties together all the points made in your document?
2. Tasks – Does your user guide address the user’s requirements? Check the document to see if you addressed each task and provided enough information for the user to perform the task.
3. Structure – Does the document flow? Make sure each topic connects clearly and logically. Do the topic sentences of each paragraph relate to the subject matter?
4. Accuracy – Is the information correct? Is it adequately documented? Have you tested the document so that it helps the reader to perform their tasks?
5. Language – Do you use specific language? Avoid vague terms such as in the event of, thing, factors, and over reliance on unclear pronouns like “this” and “it.”
6. Drafts – Technical Writing involves writing multiple drafts. This means that after each draft, you need to check that the edits have been included in the correct draft.
7. Read Aloud – Get into the habit of reading your documents aloud. If you have trouble reading a sentence clearly and smoothly, it probably needs to be rewritten. And if it sounds wrong to your ear, then that’s a warning sign that something needs to be corrected.

PS – I also use a checklist to check off the different tasks as I revise technical document. This is especially helpful if you’re working late or are revising several documents in succession.

One mistake to avoid is to focus on one area, for example spelling, and overlook other areas, for example, the accuracy of the material. While the reader may forgive you for the occasional spelling mistake, they won’t be impressed if the material itself is incorrect.

How do you revise your documents? What mistakes do you see most often?

About the Author: Ivan Walsh is a technical writer with a weakness for documentation plan guides. His also runs a video marketing blog at www.videocameraschool.com

Posted via web from Technical Writing Tips

Filed under: technical writing

How Tai Chi Will Make You a More Successful Technical Writer

Post written by Ivan Walsh. Follow me on twitter

I spend 10 hours a day writing user guides, online help and other such delights. One of the hazards of working these long hours is migraine, back pain and (literally) a pain in the neck. You can get away with this in your 20s, but as you get older you need to take greater care of your health. I really hate jogging (: and looked for an alternative form of exercise. I found Tai Chi.

 

The Tai Chi Guide to Technical Writing

I start work at 6 a.m. most days. By 12am I’m ready for a break. Usually I walk by the canal or hit the gym. But, it gets a bit monotonous. All those thread-mills pounding along. And no-one ever looks happy in the gym. All so serious – fight the flab!

My local gym (I’m in Beijing, great place!) offer Tai Chi classes every Thursday. So, why not? Along I went.

Now, I’m pretty sporty and have done yoga, dancing and other such activities.

How hard can it be?

It is really hard.

No, really, really hard.

What’s difficult is the simplicity of the whole thing

If you tighten up, get tense, or start to get negative, then you’ll lose your footing and look a bit of a clown. Luckily, our teacher (it’s a group class) is very calm and shepherds us along. Bit by bit we got there.

Remember all of this is in Chinese – and you know more Chinese than I do!

At a certain point, I felt defeated. Despite my best efforts, I could not get it.

Also, I’m left-handed (first excuse!) so I ended up doing all the steps back to front, backwards and upside down. It really was crushing but I kept a brave face and went on.

By the way, all the others were ladies — and no-one spoke a word of English. Let’s say I soon became light entertainment.

Why not?

But then it clicked.

I did a few turns, swayed this way and completed a small routine. A minor triumph. After that I went home and re-started on my technical writing.

So, did this improve your user guides?

Yes.

Tai Chi makes you:

1. Stop your mind.

For this I am very grateful. It’s so difficult at first, you have to just stop thinking and ‘feel’ how it works.

2. Eat less

I noticed that after I finish, I tend to eat a smaller lunch, maybe a salad and feel more calm. Not sedated. Calm.

3. Sleep better

I try to do 10 min at night when junior is in bed. It seems to slow down the machine. Thoughts, worries, deadlines melt away.

4. Less time-wasting

The lesson is about 45 min every Thursday, so I gave up a few other activities. In real terms, it meant less time on social media sites, checking email and other time-killers.

Once you stop doing these things, you realize how pointless they really are – or for me anyway.

5. Better documents

This is the acid test, isn’t it?

When you sleep well as night, eat better, feel calm, are in less pain, and waste less time twittering with some jezebel, then you’re output is bound to improve.

How about you?

What do you do to take care of your health?

Do you find Tai Chi, Yoga, or other such activities really make a difference?

Posted via web from Technical Writing Tips

Filed under: technical writing

How Many Hours Per Week Do Technical Writers Actually Spend Writing?

How much time do you spend writing every week? Remember, you have 37.5 hours (I know!) for technical writing every week, but how much is actually spent writing? When I say writing I actually mean developing content, so this includes illustrations, diagrams, publishing etc – whatever goes into the final deliverable.

Christine, my former manager, kept a record of all the tasks she did during the week. Here’s a breakdown of how much time was actually spent writing.

• Technical writing – 15 hours (includes all writing tasks, such as release notes, developing videos, converting material from Word to PDF/HTML/FrameMaker and screen capture work)

• Email – 12 hours (includes correspondence to programmers, team members, sales, customers, mgt)

• Project management – 6 hours (includes status reports, scheduling, document distribution & include feedback etc)

• Timesheets – 45 min (including revisions that need to be made so we can bill the customer correctly and allocate resources to the correct ‘bucket’)

• Internal Meetings – 6 hours (Mon & Fri office meetings, Tech Publishing Thursday meeting & meetings with HR (assessments) and project coordination meetings with Development)

• Customer meetings – 4-10 hours (this includes conference calls, status reports, emergencies, monthly conf calls with global depts, and project handovers. Mostly status updates)

• Travel – 6 hours (i.e. to customer sites or downtown to our HQ)

Total – 43-49 hours (50+ if you add in the travel)

Does this surprise you?

Less than 15 hours (30% approx) was spent on documentation. The rest was sucked up with email and meetings. While there are ways to reduce time spent on these, other areas are outside her control.

5 Mandatory Tasks

She has to:

• Go to customer sites

• Submit Status Reports

• Attend conference calls

• Deliver updates

• Create documentation

There is no wiggle room there.

7 Ways to Save Time At Work

But we found some ways to create time.

• She attended team meetings but left after giving her presentation.

• She stopped attending meetings where her input was not required, e.g. general progress reports. She asked for the Status Reports from the PMs, accepted/rejected her tasks, and got back to work.

• She worked from home every Tuesday (and later every Wed). This let her work – without interruption – for 10 hours.

• She booked conf rooms – just for herself – locked herself in and worked away in peace. When she worked at the desk, people kept interrupting.

• She ignored all emails – except high priorities – for 24 hours. Why? Many small things resolved themselves. People found the document they were after. People didn’t need something anymore.

• She ignored low priorities for 72 hours. Why? Many emails were just total time-wasters. Spending time on this robbed her of time in other areas.

• She turned off her Blackberry, im and email when working. She checked these on the dot at 11 am and 3pm. Between then, she was ‘working’.

What Christine did was prioritize her work. Providing she met her deliverables – or exceeded them as was now the case – her managers were fine. Co-workers had to change their expectations, i.e. she was not available for idle chatter, “How do I move a pig in Farmville?”, or activities that removed her from her goal.

What makes here different is that she has a definite goal. Her aim was to be more productive and get the recognition. Many people do the donkey work but don’t get the credit for it.

By using her time well, she showed senior mgt that she was a cut above the rest. When I left the project, she became the Team Lead.

How about you?

How much time do you spend actually doing what you want to do? How do you stop others from wasting your time and pulling you away from your goals?

PS – I updated my profile on LinkedIn (http://www.linkedin.com/in/ivanwalsh) I recommend this site if you want to get in touch with other tech writers. 

Connect with Ivan at

Ivan: http://www.ihearttechnicalwriting.com
Twitter: http://twitter.com/ihearttechdocs
Facebook: http://www.facebook.com/ivanwalsh
Businessweek: http://bx.businessweek.com/profile/ivan-walsh/iwalsh905/

Disqus | Flickr | LinkedIn | Delicious | Google Reader

Posted via email from Technical Writing Tips

Filed under: technical writing

5 Ways to Survive an Interview with Me

Normal 0 false false false EN-US X-NONE X-NONE <!– /* Font Definitions */ @font-face {font-family:”Cambria Math”; panose-1:2 4 5 3 5 4 6 3 2 4; mso-font-charset:0; mso-generic-font-family:roman; mso-font-pitch:variable; mso-font-signature:-1610611985 1107304683 0 0 159 0;} @font-face {font-family:Calibri; panose-1:2 15 5 2 2 2 4 3 2 4; mso-font-charset:0; mso-generic-font-family:swiss; mso-font-pitch:variable; mso-font-signature:-1610611985 1073750139 0 0 159 0;} /* Style Definitions */ p.MsoNormal, li.MsoNormal, div.MsoNormal {mso-style-unhide:no; mso-style-qformat:yes; mso-style-parent:”"; margin-top:0in; margin-right:0in; margin-bottom:10.0pt; margin-left:0in; line-height:115%; mso-pagination:widow-orphan; font-size:11.0pt; font-family:”Calibri”,”sans-serif”; mso-ascii-font-family:Calibri; mso-ascii-theme-font:minor-latin; mso-fareast-font-family:Calibri; mso-fareast-theme-font:minor-latin; mso-hansi-font-family:Calibri; mso-hansi-theme-font:minor-latin; mso-bidi-font-family:”Times New Roman”; mso-bidi-theme-font:minor-bidi;} .MsoChpDefault {mso-style-type:export-only; mso-default-props:yes; mso-ascii-font-family:Calibri; mso-ascii-theme-font:minor-latin; mso-fareast-font-family:Calibri; mso-fareast-theme-font:minor-latin; mso-hansi-font-family:Calibri; mso-hansi-theme-font:minor-latin; mso-bidi-font-family:”Times New Roman”; mso-bidi-theme-font:minor-bidi;} .MsoPapDefault {mso-style-type:export-only; margin-bottom:10.0pt; line-height:115%;} @page Section1 {size:8.5in 11.0in; margin:1.0in 1.0in 1.0in 1.0in; mso-header-margin:.5in; mso-footer-margin:.5in; mso-paper-source:0;} div.Section1 {page:Section1;} –>

Yes, I’m that terrible person who interviews technical writers and asks those awkward questions. Here are some of the things I’m looking for when I interview people.

First, companies expect that graduates will have the same (more or less) writing skills – that’s a given. So, what they’re looking for are other qualities.

Such as?

• Problem solving skills – describe a problem you had and how you overcame the issues. Be modest & don’t tie yourself up in knots.
• Collaboration – demonstrate how/where you collaborated with others. I don’t mean email or twitter but, for example, how you took responsibility (“the project was running behind schedule, so we decided to hold a workshop…”) and how this resolved the issue at hand.
• Technologies – talk about an area you have some expertise. Show how this solved problems (always be the person who solves problems and gets things resolved!) and the benefits it offers.
• Memberships – if you’re a member of the STC or local IT group, talk about it. Paint a picture of someone who is savvy, interested in the community and likes to interact.
• Goals – they want you for the long term. Hiring is expensive. Interviews cost money. Describe your career path and where you want to be. Discuss how this company helps you realize your goals.

Can you see the difference this makes?

Instead of hiring a person just because they’re out of work, the company is getting someone who shares their vision.

Other things to remember

Who does the interview – many companies don’t have a technical writing team. This means the IT manager (or PM) will do the interview. If this is the case, do your prep work and expect questions about code, schedules and other area.

• Privacy — HR people may ‘hint’ or suggest that you discuss your lifestyle. Keep it simple but be polite.
• Tests – many companies will ask you to do a 45 min test. Expect this. Don’t be alarmed if they pull this out of the bag at the end of the interview. They shouldn’t do this but some people are like that.  

Things not to do at your interview

I’m looking for someone to write documents – someone who is low maintenance. You need to be that person. With that in mind, don’t:

• Arrive late – give yourself time to part the car, find the office, have a drink and calm down, especially if it’s a long drive to get there. Have a light snack (e.g. banana) before going in.
• Wear heavy cologne or perfume. In a small room, it can be over-whelming
• Eat garlic or other such foods before the interview. See above. Mouth freshener never hurt.
• Run down your previous employer. If reflects poorly on you and makes you look petty. Talk them up.

“It’s a great company but I want to move into XYZ, so I thought I’d speak to you.”

Be the type of person you’d like to hire.

Steer clear of the following:

• Religion
• Politics
• Gossip
• Extreme ideologies
• Age
• Family

it’s none of their business!

Allude to them, e.g. your family, if you wish but keep it brief. Don’t get too buddy-buddy. This is an interview. Keep it professional.

and then…

• Ask questions. This is the single biggest mistake interviewees make. They don’t ask questions. They think that being silent shows respect. Of course it does, but open up. You must have questions. Ask them. I want to hear what you think of the company.
• Show your interest. I used to print out the company annual report and discuss sections with the interviewers (when looking for work) – this blew them away.
• Quote things for their site. Talk about the company — as though you already worked for them.
• Social Media — have you joined their Facebook page? Do you follow them on Twitter. If not, why?

Don’t think of yourself as just a graduate, or an out-of-work 40 something.

Dont’ run yourself down.

You’re a potential asset to the company and if THEY make the right decision, they will hire you!

See the difference?

What the most difficult question you were asked at an interview?

 

Regards,

Ivan

Beijing, China

HTML clipboard

Ivan: http://www.ihearttechnicalwriting.com
Twitter: http://twitter.com/ihearttechdocs
Facebook: http://www.facebook.com/ivanwalsh
Businessweek: http://bx.businessweek.com/profile/ivan-walsh/iwalsh905/

Disqus | Flickr | LinkedIn | Delicious | Google Reader

Posted via web from Technical Writing Tips

Filed under: technical writing, Uncategorized, white paper, guidelines, Template, white paper

Why did You Choose to be a Technical Writer? Accident or Design?

Why did you become a technical writer? Some get tech writer by accident (me!) while for others it was part of their career path. I spoke to some technical writers about this recently. Here’s what I learned. 

How I got into technical writing

1. Accident – Karen started in journalism and discovered technical writing by accident. She felt that technical writing suits people who enjoy communicate and learning new stuff. If you like/love technology, you’re half-way there, if not, chose another field.
2. Out of Manufacturing – after 10 years in engineering, another colleague saw the ‘writing on the wall’ as the US began to lose its manufacturing jobs to China, India, and Eastern Europe. Moving into technical writing proved an exit route. However, as technical docs are now getting off-shored, she’s considering moving into another field, possibly teaching.
3. Career Choice – new technical writers (especially in India and China) have decided on Tech Comms as a career and taken the appropriate degrees, such as English, Communication and, in some cases, Journalism.
4. Career Change – JP did a postgraduate in biology and moved into technical writing as it allowed her to combine her daytime job (technical docs) and real passion (travel writing).

Technical Writing (tech comms) is a very hot field in India, offering an attractive career for university graduates. Think Silicon Valley, late 90s and you get the idea.

How I became a technical writer

I started as a programmer (anyone remember Cobol? Fortran?) but was moved into tech docs during a downsize. I studied computer science in university and though the move at the time seemed a backwards step, it’s served me well.

Coding didn’t suit me. I signed up as others did at the time without understanding the field.

Remember, I’m from a very small town in the west of Ireland so the career advice we got wasn’t the greatest. Most teachers had no experience on PCs in the 80s. What they suggested was based on what the Dept of Education recommended.

So, for me personally, it wasn’t the smartest move but  it opened others opportunities later. I landed many contracts because I know how to write code and run simulations. Most other English majors could write (way better than me) but had limited technical skills.

Since then I’ve lived in the UK, US, Amsterdam and China, so it’s worked out quite well.

I have some concerns for ‘old school’ writers who don’t always see the shape of things to come.

You need to keep moving forward in this industry or risk getting left behind.

One last thing

India has an advantage as its education system values/prioritizes maths, while most all young Indians speak English.  So, it’s a terrific combination.

China, in contrast, lacks these language skills. So, the focus there is on development.

India is going to get stronger and stronger, especially if the government fast-tracks infrastructure development.

US technical writers will lose their jobs to India. I can guarantee it. It’s a done deal.

But…

There are tremendous opportunities for those who have the gumption to move there and help develop this industry.

India lacks experienced writers, projects managers and team leads. If you have these skills…

UPDATE – I had some comment by email. Most seem to have moved into tech docs by design. However, quite a few are now saying they to move out again to find work.

What careers do you think are open to them?

By the way, 3 of these emails were from people outside the large metro areas so contract options are very thin.

Any ideas?

HTML clipboard

Ivan: http://www.ihearttechnicalwriting.com
Twitter: http://twitter.com/ihearttechdocs
Facebook: http://www.facebook.com/ivanwalsh
Businessweek: http://bx.businessweek.com/profile/ivan-walsh/iwalsh905/

Disqus | Flickr | LinkedIn | Delicious | Google Reader

Posted via web from Technical Writing Tips

Filed under: technical writing, Uncategorized, white paper, guidelines, Template, white paper

User Guide vs User Manual – which one is Right?

 

Let’s say you’re setting up a new Tech Docs Dept. You need to create new guidelines, style guides and naming conventions. Should you call the user ‘documents’ User Guides or User Manuals? Which one is Right?

I was asked this question by a colleague in India who is setting up a Technical Publishing Dept in Bangalore.  He wants to go with user guide—me too, actually.

1. When I worked in the UK it was (mostly) referred to as a User Manual
2. Whereas in the US, it was a User Guide. I think the Americans (and me!) like things to be short and to the point. Guide is just that little bit quicker to write.

Saying that, there is no right and wrong, but I did a little fact finding first.

What Google says about User Guides

I searched Google and came up with these results.

• 15,600,000 for “user guide”
• 10,700,000 for “user manual”
• 5,210,000 for “user’s guide”

What surprised me here was that User’s Guide was so widely used. I’ve always found this a bit annoying. I just don’t like hyphens, I guess.

Top 5 Most Popular User Guides

A quick check on the most popular user guides showed the following. Not what I expected.

• Google Earth User Guide – http://earth.google.com/userguide/v4/
• iPhone User s Guide – http://manuals.info.apple.com/en/iphone_user_guide.pdf
• Patron User Guide – www.ebrary.com/corp/…/en/User_Guide/ebrary_Patron_User_Guide.pdf
• Adobe Reader Help – www.adobe.com/products/acrobat/pdfs/acrruserguide.pdf
• User Guide Tutorial – www.klariti.com/technical…/User-Guides-Tutorial.shtml

Even IBM gets confused

Next, I checked IBM and Microsoft  to see what term they used.

• 15324 for user guide
• 1047 for user manual

So, they prefer user guide. Though, you’d think they’d make this mandatory. Of course, it’screenshots not easy when you have offices in every corner of the world, so let’s cut them some slack.

Microsoft prefers User Guides too

The folks are Redmond were more consistent with

• 1.8 million for User Guides and only
• 73k for User Manuals

And, to be fair, many of the user manuals were actually guides when I checked. Someone check that search engine!

Is Apple different?

Yes, of course.

Apple prefers the term User’s Guide. Like I said, I never bought into this. I prefer short, snappy titles. We don’t call them System Administrator’s Guide, do we?

Well, of course, some do.

Some things to consider when naming your documents

• Ask your target audience what they expect.
• Avoid obscure or unique terms for your documents. Use industry standard terminology.
• Create a Style Guide or adopt one, e.g. the Microsoft or IBM style guide.
• Develop a naming convention, e.g. a structure approach so that all documents are named, filed, and indexed correctly. 
• Develop a numbering convention. Show people how to number documents, for example, when to go from 1.1  to 1.2 and when to go from 1.2 to 2.0.
• Be consistent.
• Be patient when they get it wrong.

My career really began to take off when I saw myself as an ‘enabler’ rather than a tech writer. My identify of who I was changed from a guy who cranked out docs to someone who helps others get their projects done.

People want to learn, do your best to help them get there.

What do you think? What’s the most practical way to name documents and setup a new Technical Writing Dept?

 

Regards, 

Ivan

Ivan: http://www.ihearttechnicalwriting.com
Twitter: http://twitter.com/ihearttechdocs
Facebook: http://www.facebook.com/ivanwalsh
Businessweek: http://bx.businessweek.com/profile/ivan-walsh/iwalsh905/

Disqus | Flickr | LinkedIn | Delicious | Google Reader

Posted via web from Social Media Tips

Filed under: technical writing, Uncategorized, white paper, guidelines, Template, white paper

Flickr Tip: Make a Slideshow & Gallery of other People’s Photos http://ping.fm/wjUfA

Filed under: technical writing, Uncategorized, white paper, guidelines, Template, white paper

A Handy Tool for Adding Screen Captures in Gmail and Google Docs (http://ping.fm/Jrb5z)

Filed under: technical writing, Uncategorized, white paper, guidelines, Template, white paper

Searchtastic Aims To Extend Twitter Search Results With New Engine (http://ping.fm/yr6sp)

Filed under: technical writing, Uncategorized, white paper, guidelines, Template, white paper

What is Social Media Optimization? (http://ping.fm/xKr5m)

Filed under: technical writing, Uncategorized, white paper, guidelines, Template, white paper