Advice for new technical writers

Here are the responses we received when we asked, share one piece of advice you have for new technical writers:

Start with the question “why does the reader care?” and you won’t go far wrong

lornajane

Find a balance between:
(1) Take feedback well and constantly improve
(2) Develop a thick skin to criticism and have confidence in your abilities

starfallprojects

What @lornajane said… And learn to discuss why what you think is important to engineering types over, and over again.

chrisward

Keep a record of your “silly” questions, especially if you’re jumping into unfamiliar terrain. Later, you’ll benefit from being able to recall what it was like to be new, and this can improve your ability to connect with and assist your readers.

james.rhea

1- Don’t be afraid to argue.
2- If someone says no, find out why.
3- Argue until you understand.
4- Understand well enough to explain it in general terms to a roomate or friend (I call it the “interactive rubber duck”, since they can respond but probably don’t have any insight into the actual issue).
5- In lieu of an established persona, document it so that friend could follow the instructions.
6- Don’t sacrifice readability or document UX while chasing the fever-dream of pedantic correctness.
7- Learn from your seniors, but do not fear them, nor suggesting ideas to them.
8- Don’t be afraid to argue…

DigitalCommodore

Ask… And if you don’t understand the answer, don’t be afraid to ask again.

tanja

1) Learn your topic (As a documentarian, you’re a teacher!)
2) Start writing as soon as you know **something** about what the reader needs to know. (You don’t have to know everything — Small chunks of text are OK.)

mikejang

Be zealous, inquisitive and positive. If you have a frustrating day and feel like you don’t know anything pick yourself back up and try again – it will all become clear in time.

Imogen Scott-Chambers

Learn to add value- integrate with the team and the product. Think content interactions starting with the product not just as independent deliverables but also UX and UI content where you can add value. Start with user needs and work backwards.

Shalini Narang

Know your worth.

Dawn Baird

Find contracts/roles with companies that have products/solutions you’re interested in. It’s easier to learn and write about subject matter that interests you.

Ferry van der Vorst

Mind your punctuations and your sentences will take care of themselves. 😉

Soumya Subhra Guha

Become a lawyer. Or a dentist. Or a plumber. That way you won’t spend the next 40 years trying to justify your existence. 🙂

Mark Baker

Be fearless and ask questions. A lot of questions. (edited)

Swapnil Ogale

Observe and absorb

Sowmya Kumar

Always maintain a good relationship with, and be respectful to, the engineers. Even if you don’t agree with them, or if they are annoyed that you don’t understand something when they overload you with technical details that are over your head. Or if they cross out almost your complete document when they review it. It is not always easy dealing with engineers, because some can be very particular. But, you will be using up a lot of their time with your questions and requests for review, so it is essential to make the relationship work. Being a tech writer is only partially about writing documents. At least half is about understanding and appreciating people. Understanding customers, because they are the ones you are trying to help with your documents, but also understanding the people you relate to at work. That’s what makes being a tech writer such a fun and versatile job.

Erwin Timmerman

Your biggest challenge may be active listening, that is, staying focused in a discussion when 99% is mind-numbingly irrelevant to your work but the remaining 1% is crucial information.

Jason.gray

Learn the product inside out from as many perspectives as you can. Developers, product owners, marketing, SMEs, end users – everyone has something useful you can bring to the documentation.

Stay curious, because things that sound boring are usually things you just don’t understand well enough yet.

1- Don’t be afraid to argue.
…with the caveat, argue constructively, and frame your arguments from the perspective of, how does this benefit the user? Then you’re a user advocate, not an angry writer

Maggie

Ask appropriate questions. (yes, unpacking those three words takes a while. It’s still my answer here.)

steveburnett

 

Develop a thick skin and don’t take negative feedback personally. If your instinct is to dismiss negative feedback outright (because the person offering it Is a jerk [difficult to work with]), still look for the “golden nugget” in the feedback. In my experience, when I take the time to think deeply about negative feedback that at first I completely disagree with, I invariably find a golden nugget that improves my work product.

Nita Beck

Additionally, if you aren’t open to ALL feedback, or react negatively to feedback, people stop offering it. Since my goal is to make the doc better, I need feedback and welcome any comment/suggestion I get! And you are right, there is something to learn from every comment you get.

Laurie Willis

Know your target audience and learn to adapt to change.

Sean Reed

Responding to feedback will make your content great. I agree with Nita. Do not take feedback personally. If you agree with what is said apply the changes and learn. If you disagree then be confident and say why you disagree. A thick skin is essential.
Other advice is learn your writing craft. dedicate time to grammar and spelling and be aware of the requirements of Plain English and Structured Documentation. When you are confident with that you will always be able to argue you case.

Dee Vincent-Day

Know who you are writing for and pay attention to readability, grammar, company standards and processes. Ask questions and listen. Cultivate relationships. Take notes.

Kamala Raghunath

Pay attention to every detail, if it’s not accurate and understandable it’s not helpful.

Amber D’Angeles

Be consistent in your writing. People derive all sorts of meaning from inconsistencies that you didn’t intend to convey.

Elodie Bennett

“You are not developing the content for your team, neither for your organization (whether it provides content services or whether it owns the product), and nor for a Mr. President (an investor). Your only objective is to develop content for the audience who will use this content for a specific purpose. You should eliminate all friction that stops you doing that – it can be people, culture, tools, language, or any barrier.”

Vinish Garg

Master writing in general not just technical writing.

Chris Kemp

Build great relationships.

Sharon N. Daugherty

Read ‘The Insider’s Guide to Technical Writing’ by Krista Van Laan. Although it didn’t remove the huge learning curve, it gave me a very good idea of what to expect when I became a technical writer.

Chris Lovie-Tyler

Learn to add value- integrate with the team and the product. Think content interactions starting with the product not just as independent deliverables but also UX and UI content where you can add value. Start with user needs and work backwards.

Shalini Narang

Do not accept the information given to you at face value, dig and dig deep.

Shamim Kholosi

Audience, audience, audience. If you don’t know who you’re writing for, you might as well let the developers write the documents. The worst writing will help the best-targeted audience ; the best writing is wasted on people who can’t or won’t read it.

Tim Penner

Use your authored manual to work with the application.

Samiksha Acharya

Ask more questions.
Respect people’s time.
(Sorry…that’s two!)

Bruce Corman

Know your worth.

Dawn Baird

Find contracts/roles with companies that have products/solutions you’re interested in. It’s easier to learn and write about subject matter that interests you.

Ferry van der Vorst

 

 

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.