Minimalism: Talk less, tell more

Does talking less always mean a person is shy or introvert? Or, does it simply mean that the person does not share more than needed? Now, the same line, which parts being shy and being careful, is drawn “as is” between “talking” more and “telling” more. The line – the mark of distinction – is thin, and difficult to draw. As technical writers, we perform a very difficult task – of scripting documents, despite all sorts of problems. But, more difficult it is to cut the “original script” into a lighter, edited, crispy, or sensible version (and all other positive adjectives one can think of). So, for us, carving-out that document is a skill, developing which requires learning and practicing the basics of minimalism.

Minimalism is reducing complexity and volume of content in any document. In this post, I will briefly discuss about the basics of implementing it into user documentation:

Identify the reader

Connect to the reader and understand what it takes to make him/her understand the product feature/s. One must step into the readers’ shoes or think the way the user thinks, while preparing the user documentation. I do not, in any way, intend to teach you what to write. The art of saying something is at times much more effective than the purpose of saying it. Additionally, it is possible that you might address two different levels of minds/users through one document. It is, therefore, necessary to prepare a document, which is neither too basic nor too advanced. You must use a narrative technique (which  is the art of saying), so that you address readers, rather than addressing the functionality of the product.

Use cross-reference

A simple way of connecting with such contrasting levels is to start at the basic level, and, slowly, increase the level of complexity of document. Of course, it is possible that those who did not read the first few chapters will find it difficult to comprehend the last ones, but you always have techniques of cross-referencing content, so that readers get exposed to major part of your documentation, while referring to certain functionality. The readers might not click on the references, but they will certainly know where to look for, when in need.

Improve user experience (UX)

As far as the documentation is concerned, a picture is worth a thousand words. And a description of the picture will only add to the understanding. Adding pictures, to describe procedures and features, always helps. As far as the product is concerned, make the interface intuitive and simpler.

Grammar: To the rescue

A badly “edited” documentation is much worse than a badly “written” one. Editing, if performed on a detail-level, can fetch you with far better readability statistics. The following are some of the key points, as I understand:

Cut dead words: Prefer to not to include any such word, which does not contribute to the understanding of the user.

Use hassle-free writing: Prefer to replace anything that “has been” done with “is done”. Replace anything that looks like “a majority of” with “mostly”, “due to the fact that” with “because”, “in most cases” with “often”, and “in order to” with “to”.

Avoid “techy-ness”: Prefer writing in simple terms, so that you avoid losing your reader: Simply write “use” for “utilize” or “feature” for “functionality”. I remember having read (and revised) a lot of user documentation, which accidentally (at least I hope it was so) used words like “obligatory” for “mandatory”. I could only imagine the sorry-state of readers. Also, you should avoid forming noun stacks in sentences.

Insert tooltips

The help document, as is seen mostly, is never really helpful for readers – and for more than a reason. To minimize hassle, and the need for documentation, you should have tooltips – which are simple (and helpful) and intuitive – inserted wherever possible (and required).Also, some context-sensitive examples can be provided in the help documents, along with examples, to cover case-specific information, if any.

Single source the documents

You are always welcome to implement single sourcing in documentation. Reuse and republish content wherever possible and provide enough links/references. Single sourcing has far-stretched advantages in companies that release their documentation in different languages or those that have role-based user guides.

Use wisely the points discussed: You will talk less, but tell more.

Wish to reply?

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s
https://suyogketkar.com/technical-writing/minimalism-talk-less-tell-more/
suyogketkar.com
crawl=CC-MAIN-2018-09
66791
application/http; msgtype=response
sha1:MEBMF4ZFQFERNY6VY2QK5XVSLZJI2SG7
<urn:uuid:1f8b5e40-eeb3-4076-b524-9852e0883904>
2018-02-21T15:17:04Z
192.0.78.24
text/html
sha1:TA7OTVVZFKVA7MY5R4C6NX3XBD7OCEK3
<urn:uuid:b7c211cb-183a-4bd0-973b-b86aa2f7e2a3>
https://suyogketkar.com/technical-writing/minimalism-talk-less-tell-more/
length
response
<urn:uuid:fd7bcddd-c4dc-4b52-8323-22196da09886>
robots: classic
hostname: ip-10-168-188-114.ec2.internal
software: Nutch 1.6 (CC)
isPartOf: CC-MAIN-2018-09
operator: Common Crawl Admin
description: Wide crawl of the web for February 2018
publisher: Common Crawl
format: WARC File Format 1.0
conformsTo: http://bibnum.bnf.fr/WARC/WARC_ISO_28500_version1_latestdraft.pdf