Documenting Single-Step Procedures

While working with single-step procedures, use a bullet to mark a single-step procedure.
Avoid using number to mark a single-step procedure.

Refer, the examples below to get more clarity.

MSTP Style:

  • On the Edit menu, click Update Book. (Correct)

Non MSTP Style:

  1. On the Edit menu, click Update Book. (Incorrect)

3 T’s of Technical Writing

I know while reading the headline, you might find yourself in trouble and wonder we have heard about 3 W’s but 3 T’s is like big no. Well, my reaction was also similar. But then i put my Tech Writing knowledge to practice and found something worth reading. While reading this article, you will realize that the things covered here are quite practical and obvious. It’s just that abbreviations are in demand these days.

What are 3 T’s?

So, here is an answer.

1) Technical Knowledge (First T): Being a technical writer, you need to understand the technicalities of the product. This is possible only when you are aware of the technical jargons that are being used in your product. The basic thumb rule is, you need to work like a tester and developer. For example: If you are involved in API Documentation, then you should try to test API’s just like Testers or Developers. I know some of you might ask, “What is the need?” Well, the answer is- Quality of your document is directly proportional to the technical knowledge you possess.

Take another example, many a times your manager asks you to think out of the box and we fail to understand what is actually required from us. If you are working on a user guide in Robohelp, then try to play with CSS or try to add HTML elements in the design view. Try, to do the things which you might tell your Developers to do for you. I know i might sound stupid, but believe me this would affect the quality of your document.

2) Doing it like a Techster (Second T): You need to have an eye of a Tester. Working like a tester not only enhances your domain knowledge, but it also enhances the quality of your document. You start writing crisp content which definitely gives you an edge over others. I know this may take extra hours as last min changes and short deadlines often widen the time crunch. There is a saying “For something great to happen, you need to compromise somewhere”. This might sound philosophical, but believe me this tip really works. I know it is time consuming, but it is definitely worth it.

3) Tools Proficiency (Third T): I fail to understand why people run after learning tools rather than learning the basics of writing, style, editing, proofreading etc. Being a Technical Writer, you need to understand that the tools used for documentation vary from organization to organization. Learning tools is not dime a dozen. If u r tech savvy, you can definitely learn any tool in short span but it takes time for writing a masterpiece. Every day you evolve as a writer and with practice you definitely write out of the box. Try to be the master of one rather than being Jack of all trades and master of none. Still, if you think that you can’t live without tools then pick one and learn about it in depth. Basically, you need to prioritize the tasks if you want the tables to turn into your favour.

If you have a right vision of Technical Writing, then there is no point turning back. But, Tech Writing is not just about writing Click here or Click OK. It’s about writing minimal, clear, correct, and crisp procedures from the detailed verbose content.

I hope this article proves to be your silver lining.

 

Tech Writing

‘LAR’ principle in Technical Writing

Writing Freaks

When you are writing technical documents, always keep LAR principle in mind.

L (Location), A (Action), R (Result).

Example: In the web browser (Location), open http://www.wordpress.com (Action) to create your website or blog (Result).

Here web browser is ‘Location’, opening wordpress.com is an ‘Action’ and creating a website or blog is the ‘Result’.