I’m @rey, the technical writer for Platform Engineering (SRE, Infra, Data, & Client) at Mercari. This post is for Day 11 of Mercari’s 2022 Advent Calendar series. You may have seen my colleague @josh’s blog post on personal knowledge management, wherein he outlined the benefits and methods of organizing, retrieving, and applying knowledge. This post focuses on recording knowledge, that is, writing! Here, I would like to quickly present you with some ideas — from myself and some others — that may help you become more comfortable with writing habitually and effectively.
-
Try to say it in less.
It’s a beautiful thing, the destruction of words.
— George Orwell -
In the drafting process, try writing the introduction last.
The traveler sees what he sees. The tourist sees what he has come to see.
— G.K. Chesterton -
Like in school, put your name and the date on your documents.
Education is what remains after one has forgotten what one has learned in school.
— Albert Einstein -
Multiple rewrites usually indicate a fundamental misalignment. Better to clarify what you are trying to express, and to whom, and then starting over.
Too large a revision, or too many revisions, indicate that the piece of writing is a failure. In the time it would take to salvage such a failure, I could write a new piece altogether and have infinitely more fun in the process.
— Isaac Asimov -
Don’t think of it that you “write documentation.” You write statements (sentences) that convey ideas (paragraphs) that when taken together (sections) form a conception (thesis); documentation arises as a byproduct of this effort.
All you have to do is write one true sentence. Write the truest sentence that you know.
— Ernest Hemingway -
Writing is not a big deal, and the worst that could happen is you have to rewrite everything — which is not so bad, since writing is not a big deal.
There is no such thing as a lousy job – only lousy men who don’t care to do it.
— Ayn Rand -
What you wrote, for the most part, is neither as good nor as bad as you or others may say. It is, however, exactly as important or as unimportant as you think.
There is nothing either good or bad but thinking makes it so.
— William Shakespeare -
In order of importance, a document should be: published, correct, and beautiful.
The finest eloquence is that which gets things done and the worst is that which delays them.
— David Llyod George -
Typos and solecisms are the least of your concerns.
To play a wrong note is insignificant; to play without passion is inexcusable.
— Ludvig Van Beethoven -
Approach your practice of writing with exuberance, mindfulness, and humility. Respect the time and attention of your readers, be gracious when peers seek feedback or counsel, and cherish your voice.
Be yourself; everyone else is already taken.
— Oscar Wilde
Before closing, I’d like to zoom out from composing and looking at the document lifecycle overall. I frequently find parallels between the natural world and documentation. The featured image for this article is a Plumeria in bloom that I cared for back in the States. Yet as the blossom inevitably fades, so too do documents lose accuracy and relevance. Sometimes, it is not wise to try and maintain documentation beyond a certain point. Rather, you may find it more fruitful to cultivate the culture and mechanisms that bore the original documentation, and thereby ensure that it may bear the next.
Over the holiday and year-end season, I hope you find time to relax, enjoy good company, and perhaps think a little about writing. Better documentation makes the world better. I envy the delight of your readers as they get the answers they need and expand their knowledge with the great content that I know you can write. As they say in Mercari, Go Bold!
Tomorrow’s article, for the 12th day of Mercari Advent Calendar will be by @yaginuuun from the Recommendation team. Please look forward to it!
