Archive: March 16, 2022

API Documentation
Technical Communication

Perfecting an API Guide

Mar 16, 2022 by mindivik 0 Comments

Perfecting an API Guide

What is API Documentation?

API documentation is a technical content deliverable, containing instructions about how to use and integrate with an API effectively. It’s a brief reference manual containing all the information required to work with the API.

It contains details about the functions, classes, return types, and arguments supported by tutorials and examples. API Documentation has traditionally been done using regular content creation and maintenance tools and text editors.

API description formats like the OpenAPI/Swagger Specification have automated the documentation process, making it easier for teams to generate and maintain them. A third-party developer is your API’s leading consumer, and he is trusted with the task of solving complex programming challenges.

Your API is significant for the technical user, as it is a crucial cog in the entire software value chain. They will want to integrate it as fast as possible and take their software development process ahead.

Hence, you must ensure that they immediately understand the value and usage of your API. The aggregate experience of the developer when discovering, learning to use, and finally integrating with an API is termed Developer Experience (DX). Smart API documentation is the key to a great DX.

The Need to Document APIs

Increased Awareness

A satisfied user will ensure more follow suit. The network effect is when a service or product becomes more valuable when more people use it. Your satisfied consumers will be the API’s most prominent advocates. As more users adopt your APIs and reach critical mass, there will be a probable increase in evangelism and word-of-mouth publicity by your satisfied consumers, leading to the network effect.

This is similar to our own experiences. We continually raise awareness of the great products we’ve used. It’s the same for developers. If they can easily and quickly learn to use your APIs, they’ll be your most prominent proponents.

Improved User Adoption

Adoption patterns are already shifting towards developers in the technology sphere. One big reason for having good API documentation is that it improves the experience for developers using your API, which directly correlates with API adoption.

People adopt products they enjoy using, and the same holds with your API. If you get your documentation right, more people will find value in your services easily, leading to better growth and adoption.

Saves Support Time and Costs

In addition to driving increased awareness and adoption of your API, good documentation also decreases the time spent onboarding new users, be it internal developers or external partners.

Poor or no documentation means more frustrated users relying on your team to understand how to work with your API. On the other hand, when you give users the ability to try out the API before implementing it and arm them with detailed documentation to get started, you’ll save your team countless hours responding to support emails and calls.

Ensures Easier Maintenance

Documentation leads to good product maintenance. It helps your internal teams know the details of your resources, methods, and associated requests and responses, making maintenance and updates quicker.

Developers' Guide
Technical Communication

A Developers’ Guide: A Journey Beyond Coding

Mar 16, 2022 by mindivik 0 Comments

A Developers’ Guide: A Journey Beyond Coding

Creating the perfect developer guide is the key to the success of your software and its application. They allow your target audience to quickly gain all the information they need to use your product and to start developing against your API.

With the rapid growth of API applications, it has become even more important to communicate a developer’s thought process clearly. This not only avoids unnecessary confusion, but also empowers the developer to aim beyond mere coding tasks.

How to Create the Perfect Developers’ Guide?

Keeping the Developer Engaged

Developers are first and foremost techies who love coding, tech processes and digital wizardry. However, they want their products or services implemented with least errors and hassles.

Grabbing a dev’s attention in a developer guide means showing them something they can instantly act upon. If the guide spends too much time on explaining intricate details or the subject matter, unfortunately the developer will no longer be on the same page with you.

Triggering Developer Interest

Once you’ve grabbed a developer’s attention, you need to keep them interested through easy-to-use guides and utilities. These should let them progress from a simple code snippet, to a running application. There are many ways this can be accomplished but the key is to achieve this quickly and efficiently.

The main page should provide access to a tailored and more detailed documentation. Likewise, the front page should help the dev to select one of the available languages and the code snippets are then shown in that language. Developers can also self-provision a sandbox, which simplifies the setup of their development ecosystem.

Empowering Devs with Knowledge

An involved and driven developer, who knows what they can do with your API, is now ready to delve deeper into your requirements with adequate knowledge. This can cover a range of subjects, which are as follows:

  • Understanding the “unhappy” path including error scenarios that happen out-of-band of the API call and how these are addressed
  • Using web hooks to create feedback loops for other out-of-band activities
  • Understanding rate limits, quotas, throttling, etc. that may affect how your API can be consumed

Deepening a developer’s knowledge might need them to understand the subject matter of the industry you operate in. This is because your implementation might reflect certain industry practices or constraints.

Your API might not be entirely perfect and can be coupled to an existing backend that is not RESTful in nature. Also, with experience, your proficiency in delivering APIs might still be growing. This would require certain design choices to be clearly explained to the developer.

Ensuring the Final Production Run

The success of the aforementioned processes and efforts lies in taking a developer’s application to production. This might vary, as it is largely dependent on the API provider and the type of API. The key to success is in making this process as easy as possible, with clear guidelines on the steps and process.

Luckily, free-to-use public APIs implementing no security measures can go to production quite easily. Most consumers are likely to be using a single API endpoint right through the entire API lifecycle. API providers should ensure developers are aware of this fact to allow them to develop their application as efficiently as possible.

Where an API does have a promotional model, the API provider needs to clearly state how developers will need to configure their applications between development and production.

 

Administrators' Guide
administrators guide, Communication, Technical Communication

Administrators’ Guide – Simplifying User Experience

Mar 14, 2022 by mindivik 0 Comments

Administrators’ Guide – Simplifying User Experience

A lot of effort goes into providing users a quality experience while they use a product or service. While effective user guides ensure that a user is happy with the initial purchase and installation experience, an administrator’s guide guarantees continued customer satisfaction and grievance redressal.

Who are System Administrators?

Since the digital revolution has taken over the world, System Administrators (SysAdmins) have toiled to maintain the accessibility and uptime of your most important IT services. And, while the rise of DevOps and cloud computing has led to more people with a hybrid SysAdmin/Developer skill set, the primary duties of a system administrator will always be required.

A system administrator’s role has undergone a paradigm shift in the last decade. Today’s system administrators are knowledgeable in both hardware and software – configuring resilient, secure architecture to ensure the success of the business.

System administrators are normally tasked with the installation, maintenance, configuration and repair for servers, networks and other computer systems. They work across both hardware and software applications, while operating across programming and scripting tasks as well. This helps them execute tasks and actions across their applications and infrastructure.

How to Write an Accurate Administrator’s Guide?

Opt for Tables & Matrices

A SysAdmin can significantly improve presentation and usability by displaying information via tables and role-based matrices. This content hierarchy helps SysAdmins find information faster, making the documents more useful, and reduces calls to other support channels.

Use White Space Judiciously

By making better use of white space, the Administrator’s guide becomes easier to read. This negates the need to constantly refer to supporting or explanatory text. Old-school System Administration Guides were quite difficult to read. This made users vary of referring to them, while causing unwillingness to consult the guides for information.

A Readable Font is a Must

An administrator’s guide is meant to convey maximum satisfactory information at minimum time. Opting for flashy or aesthetically alluring fonts will not cut the mustard. If a SysAdmin isn’t able to read, understand and communicate the content to the user satisfactorily, the entire purpose of this guide is nullified. Stick to a simple and readable format, always.

No Fillers Please!

The idea is to do away with unnecessary articles, adjectives, adverbs, prepositions, pronouns, and other descriptors when possible. While these do embellish an article, we must remember that the reader wants to find an exact piece of information right then. A cluttered page beats this end. Literary aesthetics can wait; a customer’s concern cannot.

Eliminate Redundant Words

Instead of saying, “in the event of”, write “if” instead. Do away with the flab and keep it crisp. In introductions, look for phrases that add little value and clog up the page. Systematically remove them. Stick to a brief introduction and try to shift to the main content: this is where the solution lies.

More Short Words are Welcome

Just like sentences, words should also be shorter and easier to understand. This not only reduces the word count, but also keeps the quality of communication intact. Remember, your success lies in addressing a user’s issue successfully and not in showcasing your command over a language.