Imposter syndrome (IS) is common in our line of work, and it may manifest into a reluctance to start writing stuff down. One may be afraid to embarrass themselves by writing to an audience larger than oneself alone. (Promoting the use of wikis, which encourages impromptu updates and deemphasizes authorship, seems to have helped little.) Part of the fear is about — while demonstrating what one knows — one also exposes what they do not. Another part is on writing skills in general.
I’m not going to parrot the brilliant essays people have written extensively about how to overcome IS. It’s the second type of reluctance that I plan to talk you out of.
The gist: An engineer does not have to be a poet to start writing documentations.
Write like Hemingway, not Shakespeare
Even if one’s writing skill was objectively sub-par, they could still create good compositions by writing with simple words and short sentences.
In the end, it’s clarity that makes people productive. Who cares if you write like a third grader? As long as your grammar is fine (i.e., not rampant enough to impede comprehension), your writing is going to be valuable to somebody, someday. (Plus, grammar is easy to fix with computers anyway — more on this later.)
But just how concise is adequately concise? As a rule of thumb, you can keep accounts of how often you get cut off during conversations. If more than half of the people you conversed with have ever interrupted your speech, you might need to work on your conciseness. (Caveat: count people who cut you off, not conversations where you got cut off, so that you avoid overweighting those with low patience and/or bad manners.)
Practice clarity through emails
To practice the skill of succinctness, emails present great opportunities.
Do you tend to write long-winding emails? work on that subject line before you hit “send”. Pretend that every single character costed a dollar, so that you would feel more motivated to pack more detail into less words. For example:
- Instead of “Can someone please help with ticket ABCD-12345?”,
identify what needs to be worked on: “Help needed on ABCD-12345: System X failure rate doubled in the last hour”. - Instead of “this tool isn’t working / broke / failed to run”, point out exactly what surprised you: “Expected a JSON object; got a base64-encoded string”.
About email threads. Fun fact: Modern email clients are smart enough to keep grouping emails into threads even if you removed that ASCII centipede of “re: re: re: re:”. Go ahead, and most recipients will appreciate your friendly gesture. Even if you are not in a good position to modify the subject line, you can still exercise your succinctness by prepending TL;DRs to your messages.
Tint it with humor and metaphors
You may ask, “aren’t simple words and short sentences going to make the writing sound dull and boring?” My answer would be to add humor and metaphors.
For example, if you have discovered a long-standing bug, you can emphasize on its maturity as if it were a person:
“The bug was so old that, if it were a baby, it should’ve learned to walk by the time it resurfaced.”
If your LoremModuleVisitor is having trouble processing LoremModule,
“Our
LoremModuleVisitorenjoys their trip toLoremModuleas much as I enjoy visiting my in-laws."
But there’s no guarantee that you can find a good metaphor every single time, and sometimes your wittiness just evades you. Perhaps it’s outright inappropriate for the corporate culture at your workplace.
Improve proses, no writing skills needed
What’s the almost mechanical, bare minimal way you can avoid boring your readers?
“Semantic highlight” your writing. Let’s take some inspiration from “syntax highlighting”, Almost all code editors visually distinguish program elements (variables, keywords, constants, etc.). You can do the same with your proses, but (of course) on the semantic level. For example, I myself vary formatting excessively in my writings:
- I bold words that I would put stress on when I read out loud the sentence.
- I cite sources by adding web links to keywords, instead of putting them in a “references” section at the end of the article. In-line links are painted blue and underlined, so they double as a visual aid for readers scanning through the lines.
- I use a list whenever 1) I have more than two parallel points to make, and 2) all ideas can be fit into a single sentence. If I feel an urge to create a new paragraph within an enlisted item, I spin the list out to subheadings. (There are 6 levels of headings in HTML, which should be enough.)
- When I feel fancy, I use less-common punctuations like dashes and semicolons.
By “semantically highlighting” your compositions, we can say that we are treating writing like coding. Similarly, we can treat editing like refactoring.
Some coding best practices share the same roots with writing style conventions. A concrete example is canceling out double negatives, which is both a refactoring technique and a writing advice.
Just like you can lean on the compiler when refactoring a codebase, you can use a program to proofread your articles. In fact, there are more choices than Grammarly. Long before AI tools gained popularity, I’ve been using web apps like SlickWrite and — looping back to my suggestion of writing like Hemingway — the Hemingway Editor.
Summary
The fear of writing documentation among software engineers often stems from imposter syndrome and concerns about writing skills.
However, this reluctance can be dispelled by embracing simplicity in writing styles. To begin writing in a straightforward manner, you can practice through emails. If the style looks too pale to you, adding a touch of humor or metaphors can make documentation more engaging. When humor and metaphors are not available, you can still make the text more accessible by “semantic highlighting” and automated proofreading tools. In a way, writing is like coding, and editing is no different from refactoring.
Remember, the goal is not perfection in writing but effective communication that empowers teams and contributes to a positive and collaborative work culture.
In the next installment, I plan to comment on the practice of info-siloing in the hope of job security. Stay tuned :)
