More often than not, your documentation acts as the face of your product, and is a crucial part of any successful product. In this article, let us discuss API documentation and a few related best practices.

What is an Application Programming Interface (API)?

An API is a way for software to communicate with one another. The most commonly used analogy to explain an API is that of a restaurant. You go to a restaurant and order food. This involves the following:

• The customer or the user (API consumer)
• The menu or the front-end
• The waiter or the API
• The kitchen or the back-end
• Food or the data to be retrieved

When you order food, the waiter patiently takes your request with all the special requests, conveys the request to the kitchen and then delivers the food at your table. This is how APIs work in the world of software. The APIs carry your request to the server or the back-end with all the parameters, and in turn, retrieve and deliver the required data.

In a nutshell, APIs help software communicate with one another. APIs are basically used everywhere, and we currently live in the world of API economy. API economy refers to the usage of APIs to improve and optimize business processes. There are different types of APIs, some of them are:

• Internal APIs: APIs used inside a company to improve and optimize their internal processes
• External APIs : APIs that are built and provided by a third-party service that allows developers to integrate their applications with external systems.

APIs have been a huge contributor to many companies’ success such as Uber, Stripe, Twilio, and so on. Making APIs a paid-service has also become a successful business model. According to Postman’s 2023 State of the API report, nearly two-thirds of respondents are generating revenue from their APIs. Of those, 43% generate over a quarter of their company’s revenue through APIs. This has made many companies to become API-first companies. The primary USP here is that APIs allow you to use existing technology to grow your product instead of building everything from scratch.

Now that we have understood the importance of APIs and why we need to build them, let’s dive deep into API documentation.

API Documentation

An API reference document primarily explains to a user how to use the API.

Every API has two primary aspects:

• The API code
• The API documentation

As mentioned earlier, your documentation acts as the face of your product, and is a crucial part of any successful product. Without the API documentation, the developers wouldn’t know the purpose of your APIs and how to use them in their product. Your API document acts as a primary source of truth for your developers.

Creating clear and concise API documentation has a major impact on the overall developer experience, which is as important as user experience in any B2C or B2B product.

Most APIs today are designed using an Open API specification. The open API specification is a standard format that allows developers to describe the API in the format that is understandable by both developers and computers, which is YAML. The following is a sample of Open API specification:

openapi: 3.0.0
info:
title: customer
version: '1.0'
servers:
- url: 'https://api.example.com'
paths:
'/customers/{customer_id}':
parameters:
- schema:
type: integer
name: customer_id
in: path
required: true
get:
summary: customer
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
customer_id:
type: integer
customer_name:
type: string
operationId: get-customers-customer_id
description: Retrieve a specific customer by ID
components:
schemas: {}

Different parts of an Open API specification are:

• Open API specification version
• Name and description of the API
• Server locations
• Individual endpoints of an API
• Response codes and their descriptions

In a nutshell, the Open API specifications allows any developer to understand how to use an API. You can also choose to create API docs using automation tools like Postman and Swagger. However, this is bare minimum.

Given the success of the API economy and the number of companies and developers creating and consuming the APIs, you can invest some additional time, money and effort into creating custom API documentation.

Best Practices

Tips to improve overall developer experience

Understand your target audience

The key to writing successful documentation relies on two factors:
1. How well you understand your product: It is extremely important to have a solid understanding of your product before you even start documenting your first draft. You cannot document it if you don’t understand it in the first place.

2. How well you understand your target audience: Another pillar to creating successful documentation, is understanding your target audience. Having a good understanding of your audience and what they need helps you weed out all the unwanted and unrelated information, making the document clear, concise and to-the-point.

For example, consider Google Pay’s API documentation. The Google Pay’s API documentation is beginner-friendly and is written in plain language throughout. The key reason being, the person consuming the API documentation can be either a developer trying to integrate Google Pay into their product or a stakeholder who is trying to decide if the API offering is the right fit for their company or a journalist who is trying to analyze the best API offering in the market. Always ensure that your API documentation is in plain language, has links to useful resources and visual aids.

Ensure that your API documentation follows the user journey

A user journey covers all the interactions that the user has with your product, illustrating the natural thought and progression of the user. Ensure that you cover everything your user might need from exploring to implementing your API.

1. The purpose of your API
2. How do they access the API
3. Specific API endpoints, requests, success response, and error responses.

Ensure that your API documentation follows the common format

Almost all the custom API documents out there use the same format so that it is intuitive to use. Most API docs use a two or three column layout — the menu on the right, the document in the center pane and the code in the right pane.

Keep your API documentation up to-date

As mentioned earlier, your product is only as good as your document. Ensure that your API documentation has a proper maintenance strategy. Ensure that you do the following for your data:

1. Update documentation for every product update
2. Periodically remove deprecated data
3. Analyze user pain points and create more effective documentation for the same.

A Few API References

Some of the successful API documentation sites that you can refer to:

• Stripe API
• Twilio API
• HubSpot
• Spotify

This article was originally published on The Communicator in the Spring 2023 edition

People and relationships form the core of what we accomplish as technical communicators. The better you understand your audience (users), the easier your content should be for them to follow. The better your relationships with your Subject Matter Experts (SMEs), the easier it is to extract information from them.

The book Never Eat Alone: And Other Secrets To Success, One Relationship At A Time by Keith Ferrazzi illustrates the significance of creating and nurturing good relationships.

Overview

This book, in a nutshell, is a networking guide. It explains the importance of having a professional network, how it spearheads your success and provides actionable insights on how to build and nurture your professional network.

The book has five sections, each explaining different aspects of networking. The author starts by explaining the importance of having a networking mindset. When you are ready to help others, they often come forward to help you. Success is not about elbowing your way to the front. Instead, it is about finding opportunities to collaborate with others and help them succeed.

About the Author

Keith Ferrazzi is the founder and CEO of the consulting company Ferrazzi Greenlight. He is a successful entrepreneur and a marketing expert. In this book, he shares his tricks and tips on networking. He illustrates each aspect of networking with a story or an incident taken right out of Keith’s life, sort of like a biography, which makes this book an engaging read, rather than just a rule book.

Target Audience

This is a book for anyone working in any organization or trying to build a business. As a technical writer, the book speaks to the bread and butter of what I do — maintaining good relationships. However, it would prove useful to almost anyone in whatever field. For instance, it guides people working in customer support on maintaining good relationships with their users. It also offers guidance to product owners on maintaining good relationships with the engineers who design and build their products, and thus to continually improve things.

Ideas that Strike a Spark

Generosity is the key

Creating and maintaining good workplace relationships is key to professional success. At the core of networking is generosity — being able to ask “How can I help you?” instead of

“How can you help me?.” Real networking is about working hard to give more than you get.

Good relationships lead to a more healthy and fulfilling life

According to a 75-year-old Harvard Study of Adult Development, good relationships keep us happier and healthier. The author explains this with the refrigerator analogy — How many people can walk into your homes and just open up the fridge and help themselves? Not many. People need “refrigerator rights relationships,” the kind that is comfortable, informal, and intimate enough to let us walk into one another’s kitchen and rummage through the refrigerator without asking. Close relationships like these keep us well-adjusted, happy, and successful.

Lack of social relationships constitutes a major risk factor for health. Therefore, networking not only feeds your professional success, but also the happiness quotient in your life.

You are the average of people that are close to you

Dr. David McClelland of Harvard University researched the qualities and characteristics of high achievers in our society. What he found was that your choice of a “reference group,” the people you hang out with, was an important factor in determining your future success or failure. In other words, if you hang out with successful people, you’re more likely to become successful.

From very early on, the author’s father encouraged him to meet with well-educated adults from whom he could learn. He wanted his child to be comfortable with older, more experienced people, and never to fear seeking their help or asking them questions.

Build your brand

Building your brand will provide you with a distinctive identity, and attract more people to your network. To become a brand, you need to relentlessly focus on what value you add to your organization. People hire and retain only the ones they think can make them and their companies better.

Never eat alone

Constantly find ways to include others in whatever you are doing. It’s symbiotic — the more new connections you establish, the more opportunities you’ll have to make even more new connections. The network is like a muscle — the more you work on it, the bigger it gets.

This book also covers some of the other marketing-related concepts such as cold calling, leveraging conferences for networking, the art of small talk, connecting in the digital age, and so on.

Conclusion

Never eat alone provides you with the tools you need, skill sets to develop, and mindset to cultivate to build a genuine business network. Implementing a handful of them can take you a long way toward becoming successful as a professional. This book is a treasure for anyone who is just starting their corporate careers, and entrepreneurs who are trying to build a profitable business.

This article was originally published on The Communicator in the Spring 2022 edition

Introduction

One of the most important aspects of being a technical writer is being able to extract information that other people don’t know how to get. You can do it in many ways, such as: diving deep into different functional documents or wikis, through trial and error, or even by skimming through code. However, anybody can do that. What sets you apart as a technical writer, is the ability to get information from people who aren’t very forthcoming. It is all about setting up meetings with the appropriate individuals, asking them the right questions, and getting the correct information out of them, which is then used to create your documentation. Maintaining good relationships with your Subject Matter Experts (SMEs) and other (human) sources is at the heart of this, and that is what I will address in this article.

SMEs have strong technical/specialist knowledge and technical writers are rich with information design, translational, and communication skills.The purpose of this article is to highlight techniques to maintain a positive relationship with your SMEs; this can have a significant impact on the quality of your documentation.

Why does it matter?

The simple answer to this is, writing can only take you up to a certain level. More often than not, the information that you need to build documentation is not available online. The data that we can extract from research, exploration, trial and error, and internal docs is limited. You cannot write useful documentation if there is a lot about the subject that you don’t know or don’t understand.

The only way to get all the information that you need is from the SMEs; mostly through meetings (otherwise known as SME interviews). It is essential that you identify the right people and ask the right questions to get the information you need. Once you’ve done that, your documentation will have all of the answers, and people will trust it as the source of truth, which is your ultimate aim.

Being prepared for the meetings

The worst thing a technical writer can possibly do in an interview with an SME is say, “OK, describe the feature/product to me.” SMEs appreciate it if you arrive prepared and have tried the product or feature before the meeting. This approach will aid in the development of trust and credibility among your SMEs. It also demonstrates that you value their time and provides a nice starting point for the conversation.

Asking the right questions

When it comes to asking the correct questions, there is always a sweet spot. While it’s important to ask clever, well-informed questions, it’s also not a terrible idea to ask some basic ones (if you are not able to find them through any other means). There may be another user who has the same question as you and would appreciate it if you answered it in your documentation. However, it is important to remember that if you can find the solution to a simple query through research, trial and error, internal documents, functional documents, wikis, or by going through code, it’s not worth taking it to the SME. Also, it is always best to mention your assumptions and the steps you took to arrive at the intended outcome during the meeting.

Establishing focus

It is vital to have a clear understanding of the goal of the meeting with the SME and the desired outcome. When the agenda is unclear, the entire meeting might quickly devolve into a hazy information sharing session. It is critical to understand what information you require, why you require it, and how it will benefit the customer/end-user.

Here is a technique that might be of help: as you are working through your documentation, trying to incorporate everything you know, you will have a lot of questions. You can jot them down and create a list, then, when you have gathered a set of 20–30 questions, you can set up a meeting with the concerned SMEs. You may email them this list of questions while you’re setting up the meeting and tell them you want to go over them in the meeting. People are unlikely to refuse if the aim of the meeting is made crystal clear.

Recording meetings

A technical writer’s work is typically described as converting information from SME’s jargon to plain English. SMEs are well-known for having their own language, and the information they provide during SME meetings is sometimes too overwhelming to grasp. If you are unable to absorb the information shared in the initial meeting, you may need to schedule more meetings with them, which might tire them. It might also be difficult for you, since you may have to rummage through your memory for facts you’ve forgotten or missed.

A simple solution to this is to record the meetings. You may then go over them again and again, carefully piecing them together. If the project is delayed for any reason, the recordings will allow you to refresh your memory even weeks or months later.

All the information that you need to write docs is pretty much inside the SME’s head, but it often comes out in random structures and tangents and in ways that are hard to understand. A recording allows you to shape and control that information. You can then turn to the notes and turn them into documentation.

Being curious

This goes without saying and is self-explanatory. Curiosity for technology and a desire to solve linguistic puzzles are essential qualities for a technical writer. It not only answers a lot of your questions, but it also lets you document and share your journey with your users. When you can explore and uncover as many answers as possible on your own, the quality of the questions you ask SMEs improves, and the quality of the dialogue during SME meetings improves as well.

Responding quickly to emails and messages

The quicker you respond to emails and messages, the more people feel connected and listen to you. Being responsive aids in building rapport and trust. In fact, the faster you respond, the fewer details you need to include about that particular issue or problem. It is essential for a technical writer to be as approachable as possible, and one way to establish that is by being responsive.

Prompt responses encourage SMEs to share additional information. Particularly if they are currently in the middle of a problem, and typically they may share extra information when you ask follow-up questions. Such conversations build a relationship of trust, whereas when you wait days to react, the topic dies and people eventually lose interest.

Conclusion

It is extremely important for technical writers to go above and beyond to maintain a good relationship with other team members such as engineers, developers, project managers, and support specialists since it somehow or other has an effect on the quality of the documentation being produced. Working with SMEs is one of the most important skills that a technical writer will develop over time and as they gain experience.

References

Judgie, A. Halap, C. Chaix, M. ‘SMEs and technical writers: a win-win
relationship’. CDMM. 2014.

https://comtechp7.hypotheses.org/files/2015/11/2014-Chaix-Manon-
Halap-Caroline-Jugie-Aur%C3%A9lie-1.pdf (accessed 19 Jan, 2022)

Johnson, T.’A tip for doc reviews’. I’d rather be writing. 2020.
https://rb.gy/nmpnvc (accessed 19 Jan, 2022)
Johnson, T. ‘How to become a 10X technical writer in the workplace’.
I’d rather be writing. 2019. https://rb.gy/pqwmzc
(accessed 19 Jan, 2022)

Summary: I recently chatted with Juliana Meyer, a technical writer at VTEX and host of The Manuscript podcast, about the trends and challenges in technical writing.

Below is the description of the podcast from The Manuscript’s site:

We will be meeting tech writers around the world in this new season, so we can understand what’s the market like going beyond major tech writing hubs, and also the trends and challenges that tech writers in different countries face.

In this episode, we travel to India to interview Sneha Sridharan, technical writer at commercetools, formerly working at Zoho.

Listen here:

The Manuscript - #27: Tech Writing around the world: India

Transcript

I also created a transcript of the podcast below. (Juliana’s questions are in bold; my responses are in normal font.)

Introduction

Hi there!

Welcome to the Manuscript. I am Juliana Meyer, and in this podcast, we are passionate about writing and technology. Every couple of weeks, we talk to people making a difference in the intersection of writing and the development of technology products; covering technical and UX writing, product development, art & design, content strategy, and anywhere else there is someone thinking about content in digital products and the tech industry.

If you are new here, welcome!

If you are a regular listener, welcome back!, and I bet you’ve noticed that we have a new intro song! I personally think it is very cool. It transmits our futuristic and modern vibe, along with a Brazilian twist that I really like. In fact, we released a thread on Twitter, interviewing André Josias and Dannyel Simão, our sound mixers about the process of creating this new tune. So, go check that out!

We are starting a brand new season and we also have brand new Twitter content to give a full experience for everyone listening and some more behind-the-scenes details and we will be hopefully posting episodes every week or so. So we can finish 2021 together listening to more stories about tech and writing. So welcome to season 2 of The Manuscript.

Section 1

And today we are very excited because we are taking a trip to India!

So, me being from Brazil and everything, I really think it is important to have this multi-cultural perspective on tech writing because most of the content is usually produced in western Europe and The United States which is great. We have great content being produced there and we have had people from those regions on the show before to listen to what they have to say. But also to have that plurality of perspectives and to understand what are the challenges and opportunities of technical writing in other areas is really cool and it is something that I wanna do more from now on. So, if you are a tech writer from a different country, and are just going on with your business, and actually wanna talk about it, send us an email at themanuscriptpodcast@gmail.com. This is actually how I met Sneha who will be our guest on the show today. She is a tech writer from India and also a listener for The Manuscript.

So, hey Sneha! how are you doing?

Hi Juliana, I am good, how are you?

Super great! Sneha, can you please tell me how to pronounce your last name, just to make sure that I am saying it correctly?

Sure, it is Sridharan; Sneha Sridharan.

Sridharan, is that cool?

Yes.

All right, basically, this episode, we are gonna talk about Sneha’s career and how she got into tech writing. Then, we are gonna talk about how tech writing is happening in India and its particularities, and we are gonna close things off by asking some thoughts about tech writing in general and some really hot topics that have been discussed in our area.

Cool, so without further adieu, let us start.

So, first of all, Sneha, can you please introduce yourself and share with our listeners a little bit about your path?

Yeah, sure. So, I am Sneha Sridharan. I am a Technical Writer based in India, and I am 24 years old. I live in a city called Chennai, in India. I am a computer science graduate. I have three years of professional experience. I graduated in the year of 2018.

So, a little bit about my career, I started off in customer support. I worked in my first company as a customer support executive for about 3–4 months, and then I moved to another role as a full-time writer in an ed-tech startup. And then I found this wonderful career path called technical writing, and now I am about two years into this field. Yeah, that is my career in a nut-shell.

As Juliana said, I am a big fan of The Manuscript podcast. As the pandemic started here, I had a lot of time in hand, and I wanted to just try all the tech writing podcasts. And try if I can use that to learn more about technical writing and The Manuscript was the first podcast i stumbled upon and I have been a fan of this podcast ever since.

Sneha, I told you this before we started recording, but we don’t usually get that many fan mails. So, your email to me just really made my day and I was super glad to have that connection and to actually know that there are people out there listening to what we talk about here on the show. So, really thankful for that.

I am glad that I sent out that email. I never thought I would get any response actually. But yeah, that email actually created our friendship so I am thankful for sending that email.

Yeah, I actually refresh The Manuscript’s email page like on a regular basis, just to make sure that I am not missing out any emails. So don’t worry about that. If you, listening to us, want to send us an email, I will promise that I will answer you and we will start a friendship overseas, just like me and Sneha have been doing.

All right, but going back to tech writing, I really wanna dive a bit deeper into that discovery, that leap from customer service to tech writing. So, how did that happen exactly? Was there a position open in the company and you just thought of trying that out? How did it go?

Sure, so, when I joined my first company I was still a college student. I was still interning in that company. I was so fortunate that I was given the opportunity to try different tasks, and be a part of different teams. So, I was just testing and trying every job or task that I could get my hands on just to figure out what I like the most and to figure out in which direction my career should be in. And that’s when I got the opportunity to create a guide for one of our partners. Actually, it is a point of sale software, and I actually got the opportunity to create a complete guide for our partner. I actually really liked doing that and I thought I wanted to do this full-time. At that point, they did not have an opening for a documentarian there. So, I had to move to an ed-tech startup as a full-time writer.

In that company, the role was more pivoted towards research than towards writing. And then I discovered tech writing. It was actually a perfect combination of technology and writing, my two big interests. It was a great combination of these two and I was really happy to find it, so I moved to tech writing.

Awesome! that sounds like something that I see in the Brazilian market quite often. We had people here interviewed in the show previously that moved from customer support roles and dove deep into tech writing. So, it is cool to know that we have that thing in common even though we are miles and miles away; actually, kilometres and kilometres away, because in Brazil we say kilometres.

You have a background in computer science like you said, which is kind of rare for Brazilian tech writers on the other hand. Usually, people either come from journalism or any different area really. So in the team where I work, there is me from business administration, but we have people from library studies, and also international relations, and engineering, mechatronics engineering, electrical engineering. So it is quite a diverse background. But you come from computer science, how does that happen? Is this a thing in India? Or how does that help in your day-to-day?

I wouldn’t say it’s a thing in India. But, even here, technical writers are from really different backgrounds. As you said, there are people from journalism, there are people from literature, there are even people from commerce backgrounds working as technical writers. Even here, finding computer science graduates as technical writers is quite rare, I think I am one of those. To answer your question, it does help a lot. And, knowing the basics of computers and understanding the basics of software development really helps you understand developers better. As you know, the main thing you need to create a good documentation is understanding the concept that you are documenting well, and another pillar would be understanding your users. Understanding the technical concept better will be much easier if you are from a computer science background. But again, even if you’re from a different background, it totally depends on your skills to understand complicated technical concepts.

That’s very true. We all have something to chip in on our day-to-day as tech writers, our background. Talking a little bit more about your career as well, on previous experience, you have written corporate video scripts and recorded how-to guides for features. Can you tell us a little bit about those projects?

Sure. As I mentioned previously, I was just an intern when I joined my first firm. I was working mainly as part of the customer support team. At that point the company was going through a transformation. They initially had online help, which as actually the online help pages. They wanted to move to a video library kind of support. When I had joined, they just had phone and email support and they wanted to move to a more digital form of support. They wanted to have a live chat button, and allow all their customers to get support from that live chat button. They wanted to build a bot where the robot itself gives them the relevant support that would help them. I was really fortunate to be a part of the project right from inception till its release and to get to see the reaction of customers when you force them to move from one form of support to another. It was really very interesting and I got to learn a lot more about customer support, how they handle users, and all that.

That is such a hot topic for our area, like how videos interact with our written content. I am actually planning on doing an entire episode dedicated to that topic. So, I won’t dive so deep into this conversation right now. But thank you so much for sharing your insights. That was a really cool project.

But, I am also curious to know more about your day-to-day.

It is pretty much like any technical writer. There are many phases a technical document goes through before it gets published. So, my day involves, a little bit of drafting new documents, a little bit of peer-reviewing the existing documents that my peers have shared. Or interviewing the developers or the product managers. It is a little bit of everything and also depends upon the release cycles and the priorities. And apart from this, along with technical writing, I think I’ve seen this more in India, that there is less differentiation between technical writing and developer relations.

In most of the companies, technical writers also take care of developer relations. It is the same in my firm as well. So we also take care of developer engagement like creating podcasts, creating webinars, and you know, finding out different ways to engage our developers.

That pretty much sounds like my day of work. So it is really cool to hear.

Section 2

We are entering a new section in our episode. And this section actually came from our previous conversation that we had, where we didn’t record anything but I was really curious to really understand what were the differences between tech writing in Brazil and tech writing in India. If the challenges that I faced in hiring new tech writers or establishing processes were the same ones that Sneha faced. So we are kind of bringing those questions that we had on our friendly chat into this episode. To really talk about, so basically, how are things going on in tech writing business over there. So Sneha, tell us, what is the usual profile of an Indian tech writer? You said that computer science is not really the common that you have, journalists. But what is their background or area of expertise in most cases?

I think that in most of the cases, I’ve seen many people from journalism moving into tech writing. And I’ve seen people with literature backgrounds moving into tech writing a lot. These two are more common. I don’t know if it is true with only respect to India, but as far as I’ve seen, people from journalism and literature are moving to the tech writing space a lot. And honestly, I think, the academic background is not very important when it comes to tech writing. I read this in a blog. I am not sure if I am quoting it correctly. I will just paraphrase it for you. It is that for a technical writer, there is really no traditional academic or work background that is necessary. What is important is that you can write clearly, and you can interpret code, and you can learn complicated technical concepts through a combination of doing research yourself or asking the correct questions and extracting the information from the SME.

Yeah, that’s very true. We have had John Paz, who is a tech writer at Menlo and previously worked for Atlassian here on the show. And it was really interesting to see his perspective on that as well because he does not come from a technical background but he sees it as a superpower. So being a non-techie, as he calls it, actually works out on his day-to-day. And, reading Christopher Gale and the Splunk team’s book, The Product is Docs, this is also something they mention in the chapter about hiring. It is that they look more soft skills in tech writers as opposed to really focussing on technical backgrounds. So it is cool to see that trend which brings more accessibility to the field at the end of the day because, we’re opening worlds to the technology world to people who haven’t exactly used new technology, which is great.

How do you learn how to become tech writers? Is there a university course or any format of formal education pathways or is it more learning by doing?

I would vote for learning by doing because I myself am from a technical background and I did not have any idea about technical writing when I joined as a technical writer in my firm. And pretty much whatever I know about technical writing is the one that I learned on the job. But there are many courses available like diploma and certificate courses in different universities like Arizona State and Oregon university and all that. And you can always learn from the digital learning platforms like Coursera and Udemy but there is no formal course or university degree that you can do to become a technical writer. There is one called Master of Science in Technical Communication, and that’s pretty much it.

Yeah, I feel that we face the same thing here in Brazil as well. We do not have a course on technical communication in most universities and people just land in the area and just learn as they go through online courses or blogs, podcasts, etc.

No matter how much you get to learn from the university courses that you do, it is not comparable to the knowledge that you can gain by actually taking up technical writing tasks and publishing documents.

Very true. Thanks for sharing that. But I am also curious, is there a local market for tech writing, or do tech writers work remotely for foreign companies there?

Yeah, there is a lot of local market for technical writing, and I would say it’s equal. There are a lot of opportunities in India itself and there are many Indians who work remotely for foreign companies. It is very difficult to find a technical writer, so the demand is more and the supply is less when it comes to India.

Yes, we have exactly the same thing here in Brazil. So my feeling is that companies have awakened to the importance of tech writing for like two years ago. So, now there is this race to get tech writers who have experience on the market but on the other hand there aren’t as many tech writers available with that experience that they require. So we are in the midst of a real awakening of the Brazilian tech writing market and gaining traction and more and more companies hiring and so there is lots of opportunities within Brazil, which is really cool.

What are some challenges you notice for the areas of development in India and on the other hand, what are the advantages compared to other countries that you see?

So, challenges in technical writing, I would say are finding the right people for the job is actually very difficult. Because most of them who have a technical background choose to be in more technical roles like development or testing or automation and things like that and people with good communication skills gravitate towards the roles that have more scope for writing such as copywriting or UX writing or things like that. So it is really difficult to find technical writers who have equal amounts of passion for technology as well as writing. It has actually become even more difficult to find people because of the pandemic and moving towards the remote culture has become very difficult. Also, it is very difficult to assess the skills that are required. You cannot ask a technical writer to tech-savvy enough to actually build an application and you cannot ask them to write a whole guide as well. You cannot ask them to spend 5–6 hours to write a complete guide. Assessing the candidates or the technical writers that come in is also difficult and because of that it is very difficult to find people as well.

That is very true. Since you mentioned hiring, do you feel that there are any challenges or particularities when hiring tech writers besides those that you just discussed? So, to give an example, here in Brazil, we have to teach our candidates what tech writing is. This is not such an established career that people actively engage with our hiring spots. We have to recruit people or the ones who actually land on our job opportunities aren’t necessarily aware of what is tech writing what is their day-to-day. So, there is lot of educating this audience that will be future tech writers about what it is and telling them exactly what are the day-to-day processes so that they understand if that’s something they will have an affinity with. If that’s something that they will like doing in the first place. So it is kind of tough.

Yeah, it is the same situation here as well. Because as I said, the demand is more, and the supply of good technical writers is less. So, you cannot expect to always hire people who are actually, you know, experienced in this field, and mostly when they come in, we’ll have to start educating them about technical writing from scratch. It is always a learning curve, and it takes about 6–9 months to actually complete that learning curve and to actually start contributing to the team’s tasks. It takes that much time to hire someone, and educate them, train them, and enable them to be a valuable asset to the team.

Yeah, we feel the same way. But something that is really helping out in this movement of awareness towards our area is the tech writing community here in Brazil that was just kind of accelerated last year between Breno, our former co-host of the show, Maddy and Jes, who are Brazilian tech writers as well. So we kind of got together and started calling other tech writers from all over Brazil, so we could learn with each other and produce content in Portuguese, which didn’t happen previously. That kind of ignited a really cool movement in the area here in Brazil which is also contributing in making the market more aware of the importance of the tech writers’ role, and all other consequences that we didn’t even see as part of the birth of this community. Do you have something similar in India? Do you have like a tech writing community there? Do you know other professionals in the fields? Do you produce content in your native languages, promote webinars or events? or do you mostly consume what is being produced in other countries?

We do have a tech writing community here, it is called tech writers tribe. It was started sometime last year, just to create awareness about technical writing and to educate people about the practices and the different opportunities that we have in this field. We do not produce content in our native language because India is really really huge and each state has its own language so it would be difficult. This community is common for all the technical writers in India so, we have English as our common language. So that everyone will be able to understand and benefit from that.

But that is not a barrier because just this week we had a really cool discussion in the Brazilian tech writing community of how having all the technology content basically being produced in English is a barrier to having more Brazilians engage with our profession. Although depending upon your status or your socio-economic situation, of-course, you’re going to learn English, but that’s not the case for most of the population. So that kind of is a barrier for other people to join this career. But I guess that English is more equally taught in India, is that it?

Yes, most of them will be able to speak and understand English. So the language would not be a bigger concern. So we decided that we’ll stick with English.

That’s like a philosophical question that I sometimes face myself because, I think a lot about how to contribute to the tech writing community here in Brazil. Having an English language podcast is not exactly opening doors for people who aren’t already familiarised with this language. But also there is the catch of wanting to reach beyond the Brazilian borders, and reaching other professionals all over the world who have so much to share. So, yeah, I sometimes think about that.

Section 3

So, we are entering our episode’s final section before the closing. So, just wanted to throw around some thoughts on technical writing starting with how do you see the adoption of docs-as-code in companies where you’ve worked at? Is this a topic that’s being discussed amongst your colleagues from the tech writing tribe?

Yes, docs-as-code is still really something very new in the tech comm space here in India. People are really still very confused about what this approach is and how to implement it. Even in my current firm, we are still looking at ways to implement docs-as-code as part of our documentation. So it is still very new. Just like any other new thing that comes out, people are really reluctant about it, because it totally changes how you produce documentation, right from the tools that you use, to how you allow the documentation to be reviewed by the peers and the editors and to how the documentation will be published. Considering its impact, people are still very reluctant about it, but I think docs-as-code will really grow and it will become the norm at least in another 5–6 years.

Cool. For some companies, there are blurred lines between instructional design, tech writing, and customer support. Did that occur in your career in any way?

Yes, a lot of times. At the end of the day, no matter what you do, whether you are designing instruction or whether you are doing a documentation for a feature or product or you are in customer support; all you’re trying to do is to educate the user about something- a product, or how to use a product. So I think that commonality is admissible if that’s the right word for it. I was working in customer support, but I was given an opportunity to write a guide for a partner, and to create how-to videos, create feature videos, or product-related videos.

So the final question for this segment. What’s the thing that you find the most fun about a tech writer’s career? Like what do you like most about what we do?

The most fun part would be to learn a new technology every single day and get paid for it. yeah, that would be my favourite part.

Yes, this is the answer I give people.

Being a technical writer mostly is about learning new tech, and having the ability to learn it really fast. So you get to learn cool stuff about technology, and also get paid for it. So that would be the most fun part about being a technical writer.

Exactly, this is exactly how I feel. We get paid to learn, and that is amazing that there is a whole industry of people who can do that. It is a really cool day-to-day. It is something that really motivates me at the end of our routines because the actual day-to-day can sometimes be quite challenging and I was wondering what is the most challenging aspect for you?

The most challenging aspect, I would say, is deciding how much is too much to put into a guide. This confusion of deciding how much is too much can be solved up to some extent by doing deep user analysis. However, I still find it to be the most challenging part. If you leave out some information, there is a particular set of users that you’re not addressing to and if you give too much information there is a part of users that might get bored because of that extensive detailing. So, I find this to be the most challenging part of being a technical writer.

Yeah, there is definitely a sweet spot of how deep we should go with our documentation. For me, I feel that the most difficult challenge which is also something that really excites me on the other hand may be because of my personality is how we have to build bridges between other teams in order to do our jobs. Like, I feel that 50% of my work is building relationships and building bridges and keeping them well-founded so that we are trusted by developers and product managers and also get what we need from them on a daily basis. So the PR aspect of our job is quite challenging, it takes a lot of time, it takes a lot of effort, but its also really cool. Especially, if you like the people who you’re working with.

That is so true. I often feel that technical writing is more of a personality-driven career. You’ll have to be able to create that kind of a connection with the developers, like every single time you meet them to get the information that you need and also not irritate them and throw them off the track.

Yeah, that’s very cool. Do you wanna bring up any other question or something that was on your mind with what we talked about?

I think we’ve covered everything.

Alright, So I feel that this episode, I also interviewed myself because I also answered some questions, because I really wanted to get that perspective of how things are working at least in Brazil. And it was such a rich experience for me Sneha, to have this conversation with you. And I really enjoyed how we’ve connected through this show. It is like one of the unexpected opportunities or doors that open once you start a personal project, which is really cool.

I would like to thank you for inviting me to this podcast. I really enjoyed having this conversation. I did get a lot of insights about how technical writing is in Brazil. Thank you so much.

Cool, but although we have finished our questions about tech writing and tech writing in India and Brazil, we also have two questions left on our show which is the question that we always ask our guests so, first of all, this is the moment where we ask our guest on their thoughts on the future of their respective areas. So Sneha, what trends do you see for the future of tech writing in India, since it is a themed episode.

So, there are quite a few, but off the top of my head, as I said docs-as-code is something that is here to stay and no matter how confused we are about this topic about its implementation, I believe this is going to stay in the tech comm space for a very long time. Apart from that, technical writing is something that gets evolved through every passing year, from the tools that we use to produce and publish documentation. So in the tools space, I think there’ll be a lot of changes. So, yes, these two are the things I can pull off the top of my head.

Awesome, and final question, we have another block on our podcast, which is book recommendations. So, if you’re not aware, The Manuscript actually assembled a Goodreads bookshelf with all of our guests book recommendations. So, you can check that out on the show notes or on our website. But Sneha, what book is currently on your nightstand, what are you reading right now? And what book or article would you recommend to our listeners so they can learn more about tech writing.

Currently, related to tech writing, I am reading this book called Everybody Writers by Ann Handley. It is a really cool book. It is a good book for everyone who is trying to transition from technical writing to developer advocate kind of role or who is trying to move from the traditional tech writing space to a more marketing-oriented writing space. I really like this book, I’ve enjoyed it so far. The one book that I would recommend to everyone is The Every Page is Page One book. Actually, I got to know about this book through The Manuscript podcast. I had absolutely no idea about technical writing, when I tried to learn more about things, I stumbled upon The Manuscript podcast, and the very first episode was the interview of the author of the book Mark Baker.

It was our first episode, I was not even interviewing people yet, just working on the backstage. It was just Breno’s, it was a really cool episode though.

I loved that episode, and that’s how I got to know about that book. That is one book I’d recommend to every technical writer.

Ah, there are tears in my eyes right now. You have no idea how glad this makes me feel. Because I learn so much from these interviews. I cannot describe how happy this makes me feel to know that other people are also getting enriched by the topics that we talk here on The Manuscript. That is cool.

You are doing a great job, Juliana.

Thank you! It is great to have that positive feedback, especially on personal projects to which you are pretty much a volunteer, and have that discipline and clarity of why are you doing this because I have another job. But it is great. It is fuelling me to keep going with our work.

I think this is it for our episode. How are you feeling?

I bit tired, but yeah, how are you feeling?

Exactly as I said, I am so excited that this happened. I am super glad. Thank you so much again, Sneha for all of this, you’re awesome.

Thank you!

In this post, I discuss my thoughts on the docs-as-code approach to creating documentation. This article is for technical writers, developers (with any degree of experience), project managers, DevOps and DocOps engineers, and anybody else working with or is interested in the developer documentation.

In this article, we discuss:

1. What is docs-as-code?
2. Why docs-as-code?
3. Implementing docs-as-code
4. Challenges you might face while implementing docs-as-code
5. Conclusion

1. What is docs-as-code?

Docs-as-code is an approach in which you create documentation using the same tools, technologies, and processes that developers use to create code. So what meaning does this hold to a technical writer?

• The content format: Using markdown to write content instead of the traditional HTML, CSS, and JS (various organizations are now transitioning to MDX, which is a combination of markdown and react; however, that’s a topic for another post ;) ).
• Version control: Keeping documentation up to date on GitHub or any other version control service you use to keep your code up to date.
• Doc reviews same as code reviews: Following the code review process for document review.
• Automate validation: In docs-as-code, validation scripts test the docs against fundamental use cases such as broken links (DocOps similar to DevOps).
• Managing docs using the same tools as engineers: Using tools such as JIRA to manage doc issues, report on the progress of documents at regular intervals, and show demos.

2. Why docs-as-code?

Unlike the traditional technique, where documentation is frequently the final step, the docs-as-code strategy tightly integrates documentation with the product and product development, making it an inevitable component of product release. The docs-as-code approach bridges the gap between documentation and the product, which benefits both users and the technical writers.

3. Implementing docs-as-code

Firstly, let us try and understand the code workflow.

For instance, consider that a developer is working on a feature. Let us assume that they use GitHub for version control.

1. The developer forks the current state of a working repo on GitHub, where the primary product’s code is stored.
2. After coding, the developer creates a change request and commits the changes into GitHub for review. At this stage, a few automatic validators run to detect possible errors.
3. The developer fixes the bugs (if any) and updates the change request.
4. The code is then merged into the working repository and deployed in the upcoming release.

Merging documentation alongside the code workflow

For instance, consider a technical writer working on the documentation of a feature. Let us assume that they use GitHub for version control.

1. The technical writer creates a fork of the current state of a working repository where the documentation is stored.
2. After completing the document, the technical writer creates a change request and commits the document into GitHub for review. At this stage, a few automatic validators run to detect possible errors such as broken links, typos, style-guide violations, and so on.
3. The technical writer fixes the bugs (if any) and updates the change request.
4. The document is then merged into the working repository and may either be published to the documentation site immediately or planned to correspond with the feature release.

4. Challenges you might face while implementing docs-as-code

The docs-as-code strategy does not offer a specific solution to the typical document requirements such as localization, content re-use, authentication, publishing docs as PDF, and other features that HATs offer.

5. Conclusion

All of this said and done, tools and techniques that we use to create documentation vary greatly depending on needs and use cases, both personal and organizational. The secret sauce to developing good documentation is always user research, clear language, discoverability, clarity, and correctness, as well as the quality of the review process that it goes through.

References

• https://idratherbewriting.com/learnapidoc/pubapis_docs_as_code.html
• https://pronovix.com/blog/cicd-and-docs-code-workflow
• https://www.writethedocs.org/guide/docs-as-code/
• https://www.youtube.com/watch?v=Z3e_38WS-2Q&t=2656s
• https://www.youtube.com/watch?v=EnB8GtPuauw

In a recent survey conducted by Tom Johnson on the trends in technical documentation, only 27.79% of the technical writers had chosen that they create video tutorials and screencasts. 56.82% of them have stated that they do not, and 13.65% of the writers have stated that they are planning to create them soon.

This blog post is for technical writers and explains concepts in the context of developer documentation, REST APIs, to be specific, GUI documentation, and developer relations. It assumes that you are familiar with the basics of technical documentation.

Why add videos to developer documentation?

In today’s world, there are tens and thousands of public APIs available. Many statistics also state that the number of developers who consume the APIs is also increasing day by day. So let us take a step back and think of the pool of developers who might be consuming them. These are developers with different backgrounds, different learning styles, different mental and physical needs. It is essential to create products that cater to the needs of all your users.

Significance of developer documentation

It is through documentation that developers understand your product/tool. It is not only the initial bridge through which they familiarise themselves with the product, but also they return to it when they face any difficulty in the process of using your API. It is crucial to create products in a way that it caters to the learning needs of all your developers. There are four learning styles — visual, auditory, reading/writing, and kinesthetic. Shockingly enough, most of the developer documentation that is out there is predominantly text.

When you ensure that you cater to the different learning styles in your technical documentation, it becomes easier to grasp information, learn and understand your product better. Once your users understand your product better, it ultimately reduces pressure on your support team.

Videos in GUI docs

While it is rare to see a video explanation in a developer document, the practice of adding videos to GUI docs is quite common. It is because of various reasons.

The end goal of GUI docs is simple. It is to help a user who may or may not be familiar with the software to accomplish a particular task. For instance, to guide them on how to place an order in swiggy. The scenario is entirely different in the developer documentation. Here, the goal is to introduce developers to an API or an SDK. With that tool, the developers can try and accomplish their goal (not clearly defined); more like an ingredient, with which the developers can cook any dish. For instance, to guide a developer in extracting the weather data using an API and displaying it in their application.

The major components of an API document include details like Purpose, Endpoints, Attributes, Parameters, Sample Code, Success Response, and Error Responses. We all can collectively agree that the bandwidth to add a video or a screencast to this is minimal.

So, where can you add videos in the API documentation?

A. API Demo

Instead of having a plain text explanation on what an API does and how it works, just like GUI docs, you can have a quick how-to video for an API.
Example:

B. Explaining the purpose of an API

Another instance where you can use a video is when you explain the purpose of an API.
Example:

C. Use case and case studies

Adding use cases and examples to API documents is still a debatable topic. Many developers argue that for developers to use an API to its fullest, it is best if we do not point them in any direction. In their opinion, it might restrict the scope of an API. Nevertheless, it is always nice to have a video that explains a use case that the API solves just to give them an idea.

Developer Relations

It would not be fair if we ignore developer relations when we talk about educating developers on how to use a software product or tool. For those of you who are not familiar, DevRels help developers use your products better; In other words, help them achieve their goals using your APIs and SDKs.

A recent survey on developer relations states that 22% of DevRel tasks aim at educating and supporting developers. While technical writers try to achieve the same using documentation, DevRels incorporate different metrics. For instance, seminars, workshops, engaging developers in social media platforms, and so on.

The success and the rapid growth of the field of developer relations itself is proof of how catering to different learning styles of developers and opting for different metrics can be beneficial. They make the process of learning about a product less tedious.

It is time the technical writers and DevRels work closely and make developer documentation more engaging, easy to understand, and more accessible.

Do let me know your thoughts in the comments section.

This post explains why you need postman collections and how to leverage them to provide a smooth developer experience. A postman collection is simply a group of API requests that can be saved, arranged into folders, and shared amongst the team in a workspace. Developers can fork the collection and use it to validate the APIs with minimal effort.

This post is for developer evangelists and advocates who aim to provide a seamless experience for their API users. The article assumes that you are familiar with APIs and the Postman tool.

Why you need a postman collection?

Having a postman collection saves the time and effort of your developers. They need not go through the strenuous process of building stand-alone applications to test their APIs. It is particularly helpful when a developer is just dipping their toes in the water to see if your APIs are the right solution.

Also, just like GitHub, your developers can pull and merge changes made to your collection to stay up to date with the changes made to your APIs. It is less time-consuming than reading over release notes or change-logs.

Leveraging postman collections

Once you have built a postman collection, make sure you’ve ironed out all the wrinkles before publishing it. Here are a few hacks that help you polish your collection and make it more pleasant for your developers.

1. Naming your requests

Choosing appropriate request names for APIs in your collection goes a long way in helping developers understand the purpose of an API. The postman, by default, sets the request URL as the request name. Even if your API endpoints are clear, it might look clumsy when you store an entire URL as a request name.

Here are a few things to keep in mind while naming your requests:

1. Use nouns. For example: Get Users, Delete Users, and so on.
2. Make it as intuitive as possible. Choose plain language while naming your requests, avoiding the need for developers to sift through documentation.
3. Be consistent about the noun form throughout the collection. You can either choose to name your requests with either singular or plural noun forms.
4. Be consistent about the case throughout the collection. It can be Get Users or Get users or any other case.

2. Grouping requests into folders

Organise the API calls into folders to boost discoverability.

Additionally, add specific descriptions to API calls, examples, folders, and parameters. Ensure that your descriptions are crisp and to the point. You can add them using Markdown.

You can include descriptions at three different parts of a Postman collection.

1. API requests: In the above illustration, This endpoint returns the details about the Tweet specified by the requested ID is an endpoint level description. You can additionally include descriptions of Request Parameters and Path variables as well.
2. Request folders: You can add descriptions to folders as a whole.

3. Collection: You can add a summary to the Postman collection, which is similar to the readme.md file in GitHub. You may provide general information about the collection, how to load or fork the collection, how to configure environment variables, and authorization details.

3. Adding examples

Add unique examples illustrating different parameters and status codes including all the possible error cases. Using relevant samples helps users to get a complete understanding of how the API can be used.

To conclude, I’d love to hear if this post helped you use Postman collections more efficiently, and I am certain that there are several other tips that might be useful; please share them in the comments section. Let’s connect :)

Welcome to yet another post on the Tech Writer’s Journal. In this blog, we will discuss Internal Documentation.

First things first — What is internal documentation?

Internal documentation is the process of maintaining a knowledge base of all your company’s internal processes and operations. It develops to become a single source of truth to all your employees.

The difference between internal and external documentation

1. Target audience
   The target audiences of the external documentation are contractors, external stakeholders, and customers, while the internal documentation is designed and built for your workforce.
2. Language
   The content in the external documents is much more sensitive than the one in internal documents. In the external documents, the documentarians must consider various aspects such as inclusivity and accessibility. The rules are not quite stringent when it comes to internal documents.
3. Accessibility
   The external documentation is sharper in factors such as accessibility, discoverability, and so on.
4. Tone and voice
   It is essential to maintain a uniform voice and tone throughout your external documents that unanimously represent your brand. In contrast, the only goal of your internal documents is to educate your workforce. The accuracy of the content becomes the top priority.

Why have internal documentation?

1. Save time and effort
   The newbies in your team can always turn to internal documentation than setting up meetings with seniors or working their way through them with a ton of guesswork.
2. Reduce dependency on a team member
   Your team’s internal documentation is you to your future team members (both new and old). Say a person who has been on your team for about a decade decides to leave. It would make more sense to rely on and share internal documents than to sit through countless hours of KT sessions.

Factors to consider when you start building internal documentation

1. Who are your end-users?
   Defining your end-users is quite a generic step in every documentation. For internal documents, the target audiences are the employees of your team or your organization. But you need to consider the amount of knowledge that the different sets of employees might have. The internal document might be referred by a newbie or a manager with decades of experience in the industry.
2. Easy to follow
   Having easy-to-understand language is yet another rule of thumb when it comes to technical documentation. It is always good to avoid jargon, acronyms, or complex language. Ensure that you make your document skimmable.
3. Engaging
   Yes, you are building internal documents, and making it engaging is probably the last thing in your mind. But then, remember that nobody’s going to look at your documentation if they feel that it is draining. Ensure that you do not rely solely on text. You may add examples, images, videos, GIFs and make it as engaging as possible (with corresponding alternate texts).
4. Accessible
   There is no point in creating documents that are not accessible. Irrespective of the type of documentation, the information presented must be accessible to everyone.
5. Easy to contribute
   Internal documentation is a task that is too huge to be taken up by a single team member. Allow your team members to download their brain onto a page. After all, they are the ones who are most familiar with those tasks.
6. Easy to update
   Documentation is never something that is set in stone. In contrast, it is a living, breathing thing that is evolving along with your product. The last thing you want to do when there is a process change is to manually update the entire internal document. Ensure that the process of updating documents is as easy as accessing them.

Maintaining internal documentation

1. Get feedback
   Get regular feedback from your colleagues. The easiest way to do this would be to have a comment section on each page where the developers can have a healthy discussion.
2. Assign owners and follow up
   As stated earlier, internal documentation is too big of a task to be created and maintained by a single employee. It is vital to keep the content up-to-date. The easiest way to do this is to assign owners to each process/procedure and give them access to update the document.

Taking up the task of creating and maintaining internal documents can be daunting. However, with a clear pipeline, usecases, and execution strategy in mind, you can always succeed. Consider internal documentation as an opportunity to unite all your team members to build a lifelong resource for your business and product.

References

• How to Write Awesome Internal Documentation: A Complete Guide | Slite
• How to ace internal documentation | Team Central
• Why Internal Technical Documentation is Hard
• Why it's worth it to invest in internal docs - Increment: Documentation
• Why You Shouldn't Ignore Internal API Documentation | Stoplight API Intersection
• How 5 Companies Use Internal Documentation To Scale More Efficiently | Tettra

Welcome to yet another post on the Tech Writers’ Journal. In this blog, we will discuss changelogs in the API documentation.

Recently, I had to do research on changelogs, their creation, and maintenance. This post entails the conclusions I’ve drawn, and the intent is to help other tech writers out there who want to create a changelogs for their APIs.

Without much further adieu, let us jump right in.

What are changelogs?

Although there is no official definition for a changelog, it is simply a bullet list of all the notable changes (in reverse chronological order) made to an API.

Why have a changelog?

A changelog acts as a bridge between the current version of your API and its previous versions. It has varied impacts on people with different roles. For a developer, a changelog reflects the speed of development. For a customer, it builds credibility and confidence in a product, and so on.

How to structure a changelog?

A changelog must always be in reverse chronological order — the most recent change comes first. While there are many ways to structure a changelog, here is a generic format.

By structuring your changelog this way, you make it easier for the user to skim through the changelog and absorb the content effortlessly. Also, ensure that you make changes with code breakage painfully clear. You can add them as a warning text, make them bold, or anything to make sure that your developers do not miss it.

Should you add code samples to your changelog?

In general, a changelog does not have a detailed explanation of changes made. The ideal place to add code samples and other details would be official documentation, release notes, newsletters, or blog posts. However, given that there is no hard and fast rule on what goes into a changelog and what does not, it is up to you to decide.

What are some red flags that you must try and avoid?

Here are some tips and tricks to iron out wrinkles in your API changelogs.

1. Keep a keen eye on what goes into the changelog. Present only the information that is relevant to your developers.
2. Do not ignore deprecations, especially if they lead to code breakage.
3. Present the dates in ISO format. This way, time and date information is standardized, resulting in fewer communication issues.

References

Here are some of my personal favorites:

1. https://developer.webex.com/docs/api/changelog
2. https://stripe.com/docs/upgrades#api-changelog

In this blog, we discuss the things you need to consider to make your documentation accessible to all your readers.

What is accessible documentation?

An accessible document is a document created to be as easily readable by readers with special needs. Often, making a document accessible is the most overlooked aspect of the process of documentation. It is either skipped or considered in the final stages, just before publishing the document, while it must be one of the preliminary aspects.

What can you do to make your document more accessible?

a. Knowing your audience

For any document to be clear and precise, the technical writer must be clear on the following grounds:

1. The technical concept that needs to be covered
2. The end-users of the document

Only by imagining ourselves in the reader’s shoes can we create appropriate, precise, and organized content. As technical writers, you need to know the following about your audience before you start drafting a technical document:

a. The level of expertise of the reader: Helps in deciding the depth of explanation.

b. The mindset of the reader when they reach out to your document: Helps in setting the tone and voice of your document.

c. The device in which the reader accesses your document

You can achieve these by creating audience personas. By doing so, you have a clear view of what kind of audience you are catering to and what adjustments you need to make to your document accordingly. In this step, it is important to consider making your document accessible to all kinds of readers. As mentioned before, making your documents accessible is one of the preliminary aspects of drafting a document.

b. Catering to different types of audience

Here are a few quick tips and tricks that you can follow to make your document more accessible.

(i) Use alternative texts and closed captions

• Always add alternative text to images, charts, tables, shapes, and embedded objects, and closed captions to audio and video files in your document.
• Don’t use flickering or flashing elements. They can cause anything from motion sickness to a seizure.

• Use SVG instead of PNG if available. SVGs stay sharp when you zoom in on the image.

(ii) Use meaningful hyperlinks

Do not use words like here, above, below, left, right, high and low while referring to hyperlinks. Instead, refer to the item directly such as “To know more refer to our API guide.”

(iii) Use appropriate color ratios in your document

(iv) Use differentiators other than colors in the charts and graphs

Often we primarily depend on colors to differentiate one more parameter in a graph. Instead, we can use both color and patterns.

(v) Avoid using watermarks on your images

Screen readers often skip the watermarks in images. Thus, they are often missed.

(vi) Use accessibility tools to check the accessibility of your document.

You can also use a screen reader to test your documentation. Read What Are Some of the Best Web Accessibility Testing Tools to Evaluate Your Website With? to know more.

(vii) Add accessibility disclaimer to your document

An accessibility disclaimer tells readers who and where to call for assistance with the document or presentation should they have difficulty reading or understanding it. Read How to write an accessibility statement? to know more.

(viii) Ensure that your readers can reach all parts of your document with the keyboard alone

(ix) When your document has forms:

a. Add labels to every field, outside the input box.

b. Add clear and concise error messages that are displayed above the input field.

Refer to the Google accessibility guide for more details.