Can you recall a recent example of a word you read and didn’t understand?

Do you think the writer knew that you wouldn’t understand that term?

It’s extremely important to know the professional audience you tend to write for.

Most have us have some form of imposter syndrome, meaning that we tend to believe that everyone is smarter or more capable than we are. Consequently, most of us aim our writing at a brilliant, highly sophisticated audience.

Your actual professional audience is more like you (the person in the mirror) than like Marie Curie or Albert Einstein.

Your actual professional audience consists of bright, well-educated people.

They know alot about the profession, but probably know less than you about the topic you are documenting. The CTOs of Google, Microsoft, and Facebook probably know far less about your topic than you do.

The curse of knowledge: When you (the writer) knows so much about a topic that you can’t explain that topic to someone who knows less.

Key Takeaways

• Be aware of the threat of “Pride of Authorship”
• There are times for both consistency & inconsistency
• Writing does not equal math. “There is a Universe of Possible Answers” – Barry Rosenberg

Technical Writing Fundamentals for Engineers

Materials courtesy of Google: https://developers.google.com/tech-writing/ 

Exercises at https://developers.google.com/tech-writing/one

Active Voice vs. Passive Voice

Smart writers bet on active voice – not passive voice – when writing content.

Why is writing in active voice generally better than passive voice?

• Active voice is shorter, clearer, and more modern. People mentally convert passive voice to active voice anyway. At this point, some students may object to the course’s preference for active voice.
• Some schools train students (particularly STEM students) to write in passive voice. Be prepared to defend active voice as clearer, shorter, easier to process, and more modern.

What are instances when passive voice might be better?

• When you want to emphasize the target rather than the actor. For example, in a treatise on earthquakes in Florida, the following passive voice sentence is probably appropriate: “Florida is seldom shaken by earthquakes.”

Utilizing Lists in Technical Writing

People will pay money to read lists.

The Book of Lists, first published in 1977, was the progenitor not only of hundreds of books of lists but also of all those link-bait (listicles) all over the internet that promise to solve or incite every problem. Publishers built an entire industry of lists because of the success (8 million copies) of The Book of Lists.

Why are readers attracted to lists?

1. Lists knock down walls of text (as do other visual discontinuities, such as colors, white space, tables, and figures).
2. Lists organize a chaotic world.
3. It is easier to locate details in a short list items than in long paragraphs.
4. Numbered lists simplify tasks. Think of recipes.
5. Checklists make it harder to overlook key points. Checklists make the world a safer place.

That said, don’t force every thought into a list unless that thought truly belongs in a list.

Why do we insist on writing paragraphs when readers would sometimes prefer lists?

Because we learn to write paragraphs long before we learn to write lists. Paragraphs are our go-to mechanism for written communication.

Technical Resume Tips from Dito

Resume writing is a topic all unto itself and can easily consume an hour or more. Plus, it bears little resemblance to good technical writing or even good writing at all. Sure, word choice is important, but a good resume often favors sentence fragments, popular search-engine keywords, obscure domain-specific terms, and being excessively concise while being spin-heavy.

A good resume gives enough information to generate the “I’d like to learn more about that” feeling while staying away from detail because it may get you axed before you walk in the door.

By contrast, technical writing should be concise but complete. It should convey a solid understanding while being economical on words. A good technical writer often leverages pictures to clarify the point or as a basis for further discussion.

Technical writing should never leave you wanting more detail, it should leave you feeling like, “I can’t believe it was that simple.”

KAM’s Resume Tips:

• Use LinkedIn, but remember LinkedIn does not equal Snapchat/Instagram/Texting/Facebook
• Leverage employee referrals. Significantly more likely to succeed and win-win for the employee/employer.
• Assume people who aren’t familiar with your skills/job will be first to read your resume.
• Don’t lie on your resume.
• Be wary of what you post on social media. Employers will search your public information.
• Consider open source software & leverage tools that monitor your contributions.
• Resume are somewhat old-school – be sure to update your LinkedIn profile consistently.
• Incorporate terms from the job opening on your resume.
• Research the firm to show you have not only researched the job, but the company & its competitive landscape.
• Certifications are rarely a magic bullet, but do help bolster your profile.
• People love lists! Turning your requirements/paragraphs into lists/tasks is a great skill.
• Be aware of privacy concerns with resumes.
• F-shaped Reading pattern – the most common eye-scanning pattern – follows the resume like an F.

Amy Horton’s Resume Tips:

• Use an appropriate email address that is based on your name. Avoid using numbers as part of the email and use a relevant email provider.
• Ensure that the email you use is your resume is the same that you use when applying for jobs and what is listed on LinkedIn
• Be sure to include data such as address and graduation dates. This is going away but many of the larger ATS systems still require it.
• Be truthful this includes titles. Use your official title but it is ok to note unofficial titles.
• Use bullet points but keep them concise. 6 bullet points per role MAX. 4-5 is the ideal #.
• Have someone proofread every time you make a change.
• Not so much a resume writing tip but a general job search tip: Don’t apply to roles that are not applicable to your background thinking that they may not consider me for this role but others. Those often just get rejected by the filters; especially at large companies. Use networking when there is not a role posted that fits your background instead.

Amanda Kopp’s Resume Tips

• Research the company and the role you are applying for. Tailor your resume with wording, experience, and accomplishments you have that meet the requirements of that role. Sometimes, an applicant has experience that fits the role at hand but the way they worded their resume, that experience is not listed or not written in a way that shows what they did in that role aligns to the expectations and requirements of the role they are applying for.
• Piggybacking off of that, think about how a recruiter would read the resume. Scanning for key terms, experience, descriptors that align to the job posting. Tweak your resume to include where applicable.
• Including bulleted accomplishments from the previous roles you were in, sizes of engagements/ teams you managed can sometimes provide a clearer picture of what you did in the role than a descriptive paragraph.
• SPELLCHECK & PROOFREAD. Have someone else review your resume for that feedback.
• Keep your resume 1 page, 2 pages max. Most relevant, recent experience is needed. (this one is a little controversial but it’s rare that someone will read all 8 pages of a resume). Keep it brief, keep it relevant. I’ve seen a few folks but a note in that more comprehensive work history available on linked in or a site they have and include that in the resume.

Ready to send out your updated resume? Apply to Dito!

Back to Technical Writing

Every line of code carries the burden of maintenance. Similarly, every sentence in your documentation also carries the burden of maintenance. Don’t pick up more documentation than you can carry; make each sentence in each document count.

For commercial documentation sets, consider the following additional reasons for minimizing the documentation set:

• Reducing documentation reduces translation costs.
• Minimizing screenshots minimizes the number of screenshots you’ll need to reshoot.
• Reducing documentation reduces the amount of doc to revalidate before every release.

Interested in learning more?

• Form a local writing group with your classmates. Use this writing group to conduct peer reviews.
• Hold periodic live review meetings in which each student presents a section of a document.
• Start up a “Write the Docs” group in your community.

It takes years of education and focused practice to become a successful engineer. The same goes for writing.