Documentation Is a Map: Learn to Stay on Course

Earlier this year, Lee Laster, the business development director at, contacted me and suggested that I write an article about Kueri. I read up on it: Kueri allows for end-user interaction with relational or NoSQL database resources through intuitive, natural language queries. I thought wow and I said sure because I saw that this is not science fiction. The folks at set me up with the product, and I published an article at Bit Vectors showing how to front-end a Google Cloud SQL database with Kueri. I relied on the original English-language Kueri documentation, of course. However, I read that documentation not just as a developer, but as an American technical writer with full English fluency. After I published, I mentioned to Yossi Vainshtein of that the Kueri documentation could use a little . . . “tuning“, to clean / smooth / tighten the style and flow of the material. I offered to handle this rewrite for Kueri, emphasizing that I would not change the meaning or intent of the original text in any way. Mr. Vainshtein / etc. approved, and I started in. With their guidance, I succeeded, and in no specific order, I’d like to share some of what I learned.


1) Documentation is like plumbingimage_2

Suppose we visit a beautiful house, built to modern, leading-edge architectural standards, using modern construction practices and materials, etc. We can walk inside and see nice furniture in every room. Every room has windows, each with a great view. And . . . if the plumbing does not work when we need it, we’ll remember nothing else about that house and we’ll immediately want out, never to return. For a software product, documentation works the same way. Documentation is usually not a defined core feature of the product. Still, the customers need documentation to understand that product, and they will definitely notice if that documentation does not serve them. The take-away: make sure the documentation content and delivery serve those customers as well as possible, costing them as little effort and energy as possible when they use it.


2) When your public-facing writing first goes live, don’t start thinking it will win a Nobel Prize in Literature

Mr. Vainshtein / etc. built the best Kueri documentation they could. When I diplomatically suggested to them that it could maybe use a little recrafting – and that I could help – they immediately said yes. Pragmatism meant much more to them than pride.


3) Localization covers more than grammar and spelling

Starting with correct, verified information, a non-native English writer can certainly craft documentation with correct grammar and spelling. The finished text might look great to that writer. However, the writer might not have the informal background of style and flow – heck, the slang – that only life experience in full English immersion can teach. As a result, a native reader of English might make extra efforts to read the piece because of those issues. Even worse, those issues could change the original intended meaning in unintended ways. To solve the problem, hand the piece to a native writer of English. Ask him / her to check, and if necessary tune, the text, making sure to preserve the intended meaning. Emphasize to the writer that you will explain any unclear meaning in the original writing. My work with Kueri proceeded exactly this way.


4) A native English writer will not necessarily write as well as you need, so choose carefully

Well, Ernest Hemingway did win a Nobel Prize in Literature, but I believe that someone with his writing style should not work on documentation.


5) These issues extend to all other languages

I took a one-semester Japanese language class awhile back. I learned a lot and I did really well in the class, and if I took more classes in the sequence, I would have built a competence. And . . . here we go again. I would not have “completely” learned the informal Japanese language style, flow, and slang that life in Japan would informally teach. Of course, the more someone studies, the greater the competence, but for any language, I believe this works asymptotically. The skill level closely approaches, but rarely touches, that of a native speaker. Full disclosure: I learn something new about English every day I use it.

Starting with my initial background building front-end / back-end Microsoft Visual Studio / Microsoft SQL Server products, I expanded into other software spaces, including Google Cloud Platform development. I initially launched Bit Vectors to showcase my development and R & D skills. As Bit Vectors grew, I realized that I like technical writing specifically, and writing generally, and Bit Vectors highlights these skills as well. My skills in the overall software and writing spaces made the work I did with Kueri possible.

Now, you might use English as a second language, or maybe even your first language. Maybe you or your company sell a product with English-language documentation as a core component. You might have the sense that the documentation needs improvement, but you might not know where to turn. Bottom line: for this kind of work, and for technical writing work generally, turn to me! Get in touch.

Thank you!


Frank Solomon

Blog: The Bit Vectors blog
LinkedIn: Frank Solomon
0 1976
Frank Solomon

Leave a Reply