Technical Writing Tips for GIS and Geomatics Professionals

You might be a Manager, Consultant, GIS Specialist, Geomatics Engineer, Survey Analyst, Cartographer, Spatial Analyst, GIS Developer or Remote Sensing Analyst. There are some non-technical skills that can make you rise above your peers. Among them is the ability to write well. Geomatics requires its practitioners to convey complex technical concepts to a diverse range of audiences in a lucid manner.

Many Geomatics professionals lack this ability, while there are many English majors who have trouble understanding Geomatics concepts. It takes someone with a rare combination of talents to produce outstanding Geomatics documentation.

In this article, I share some technical writing tips for geomatics professionals.

Know the Context

Before jumping into writing the actual document, it is important to understand the context. It helps if you prepare a technical brief which will force you to think about such issues upfront.

Think about the audience. Are readers technical, non-technical or a combination of both? Is the documentation targeted internally or externally? What is the level of technical knowledge of the audience?

Once you have determined the audience, you need to decide exactly what they need to know. What do they already know about the topic? How do they process information? What jobs do they perform? What are their attitudes to the subject? To produce good technical documentation, you need to interact with the audience. Perhaps socialize with them during lunch or after work. Get to know how they think, their likes and dislikes. What brands they like, what hobbies they have, etc.

Writing down the key issues, who will be on the project team and what will be the documentation approval cycle will also improve the end product.

Create a Skeleton

A tried and tested method we learnt in high school was to use an outline when writing. Outlines help us brainstorm writing projects. They might be done individually or be derived from minutes of a group brainstorming session. Either way, they organize thoughts and topic sequences. A common technique is to use a topic list, decomposed into sub-lists. Alternatively, if your document needs a table of contents, that might be used as an outline.

Add Flesh

Once you have an outline, set reasonable time frames and start elaborating the topic / sub-topic you are most comfortable with. Once a topic is done, select the next one you feel most capable of writing and get to it. Your writing does not have to be sequential. If you face writer’s block, don’t despair. Try writing about whatever that comes to your mind. Soon you will find yourself honing into the topic through this freewriting technique. At this point, do not worry about spelling, grammar and revision. Just keep writing topic after topic.

When you are done with all the topics, you have your first draft, you can begin revision. Send the revised draft to your reviewers for initial feedback. Once you have all the edits, you can decide what changes to incorporate in the document.

Make a Visual Impact

Depending on the audience, a well written piece of technical documentation might not look appealing for the readers to dive into.

To make geospatial documents attractive, make sure your headings and subheadings are well structured so that the reader can find information quickly. Headings act like milestones for readers who often skim the document quickly to find valuable information. Similarly using bullet or numbered lists makes the document easier on the eyes.

A document with lines and lines of writing can become boring or burdensome for the reader. Make sure that you break your topics into paragraphs with each paragraph being at most eight lines. Sentences, too, should avoid seeming convoluted and thus not exceed twenty five words.

Bringing documents to life by judicious use of eye candy – tables, figures, charts and photos is a great way to make them attractive. After all, a picture is worth a thousand words.

Be Clear & Concise

A long, vague piece of writing is an indication that the writer’s thoughts are unclear. Technical writing needs clear, concise language targeted to the level of the audience.

Learn to write with as few words as reasonably possible. After writing a piece, revise by playing a game with yourself where you strikeout superfluous words. Keep a positive spin to the tone of your writing. Rather than expressing a negative expression, reword it to be positive, e.g. expressing what to do rather than what not to. Another tip is to use active voice rather than passive voice. “The geomatics professional wrote the documentation” seems livelier than “the documentation was written by the geomatics professional”.

Proofread, Proofread & Proofread

Good geomatics professionals often lose their credibility because they fail to proofread often enough. Investing time in proofreading is worth the effort.

Outstanding writers spend more time proofreading than writing the first draft. That, in itself, is a significant part of their success.

Looking at the same text after in a different setting gives the author new insights for improvement. Spelling, grammar and contextual errors can waste much of the hard work a Geomatics professional put into explaining a difficult topic. It reflects poorly on their professionalism. The “track changes” feature in MS Word is an excellent tool for a reviewer to use. Suggested changes can be accepted or rejected in the final version.

Finally: Get a Second Opinion

The litmus test for good technical writing is to get it reviewed by someone who fits the profile of the intended audience. If they do not understand it, the audience will not either. Often, no matter how many times we proofread our own work, we are unable to catch certain errors. This is the same reason why computer programmers make bad testers of their own code. A second opinion sheds light on a work from a different angle, often in a manner the author could never have initially realized.