API writing

Don't be scared. It's still writing! Nowadays, with so much advancement in technology, the one buzzword that keeps buzzing around is API.

Application Programmer Interface.

The technical definition for an API would be: A library containing interfaces, functions, classes, structures, etc. for building a software application. It is used by development team to interact with and extend the software.

If you are reading this for the first time, the technical definition is surely difficult for you to begin with. Let's understand this in a non-technical language.

How about a anatomy among a patient, the receptionist, and the doctor. If you are sick, you'll call the doctor's number, and speak to a receptionist in few simple instructional language. "I'm sick. This is my problem. I request an appointment with the doctor." As a response, the receptionist will fetch your old record, understand your existing illness, go through the doctor's schedule, and will offer you a time slot for your visit.

An API does something similar. It allows you to interact with a complex system to fetch the information you need without dealing with the internal complexities.

What is our role play? We, as technical writers, need to document the interface that is connecting multiple software. Currently, RESTful APIs are the most common and easy-to-use APIs in the market. There are many other Web-based and Platform-based API too.

Do not worry when the next time you are asked to work on a API project. You need to develop the documentation and not the API! So, relax! And, Good luck!

Quality vs Deadline

It's not the first time you are facing this problem. Even in our day-to-day life, which is beyond and away from our professional software environment, we have faced this question.

Think where you are about to start cooking. Your kids are hungry. You started off to make a four-course meal and now due to the uncontrollable hunger you end up serving half cooked food. Would you do that? What would be the best thing you would do at that time? 

Similarly, in our professional environment too, we are faced with this problem on a daily basis. There's always a clock ticking constantly, sometimes even faster than it ideally should. And, we as usual, serve half cooked food! It's surely is a perfect recipe to invite illness. 

Meeting deadline is an important element of quality. Deadline is a not a different element. It should not be considered as a milestone. Rather, quality should be one of the milestones, and the deadline shall be a part of it. 

However, sometimes there comes a time when the object is immovable. In such cases, you have to let go some pieces to make room for the immovable object. When your deadline becomes such an immovable object, let go few items from your final list. Negotiate with the stakeholders. Explain the consequences of delivering a mediocre quality product. Sometimes, fixing a problem consumes way more time and effort than buying a little extra time.

Think different. Act different. Meeting a deadline is also a quality, and estimate your tasks accordingly.

Hence, change the tagline to Meeting Qualities from Meeting Deadlines!

3C - Correctness | Consistency | Clarity

Correctness. Consistency. Clarity. This is a must for any technical writing deliverable. You cannot compromise on either of these elements. As a technical writer, you have to stick to this 3Cs. 

Correctness

Imagine your Help as your GPS system in your car. What would happen if your GPS takes you on a long ride or shows you some incorrect navigation! Imagine the level of frustration that can mount on your mind! Same happens with your readers if your Help lacks accuracy. 

Your readers have opened the Help since they are stuck in a problem. It is very important to understand How and Why did a reader search for the Help in first place. Your Help has to be accurate enough to solve their problems unless they are reading a wrong answer for a right question!

Consistency

Your GPS system sometimes highlights the slowdown with red color, sometimes with yellow color. It sometimes marks the destination with a blue symbol and a couple of times with pink! What would happen? Similarly, if your Help lacks uniformity, the readers will rather need another Help to figure out the conventions. Your write-up needs to be consistent across the guide. Once you establish a tone, you shouldn't change it unless really needed. 

Clarity

Your GPS system starts showing trees, clouds, the parked vehicles, and probably some pedestrians too. Do you really need all these elements to be shown when your motive to use GPS is only to navigate it to a specific destination. Likewise, you don't need to overdo your Help. Keep it simple. Keep it clear. Don't overload it with too much information. Understand the question before you answer!

Being a Technical Writer

Who is a technical writer? What do you mean by technical writing? How does it feel to be one? What kind of role do you play in an organization? What value can you bring to the project? and so on...

These are some basic questions that pops in anybody's mind who is not aware about technical writing.

How do I do it, is a very basic question that comes in our mind n number of times every single day. Any product, any device, any software, needs instruction (except our life)! It's very common to not know something. It's not necessary we would know everything we have to do in our life. The same goes with the usage of software.

Imagine, you buy a smart refrigerator that can keep a check on the expiry date of food items stored in it! Great as it sounds! This device is equipped with an LCD panel, few touch buttons, an app download, few synchronization moves, and few technical settings. Maybe, a software engineer can do it, but what about my mom! She'll need a step-by-step guide that can help her learn the not-so-hard device.

We, the Technical Writers, write such instructions.

Technical writing is all about translating technical language into an understandable language. It is all about solving all your "How" questions!