DEV Community: Aakhil Karthikkeyan

Concise Documentation: Definition, Benefits, and how to create one

Aakhil Karthikkeyan — Wed, 15 Mar 2023 14:08:17 +0000

If you’ve read your phone’s manual or gone through the user guides for a tool you purchased, you’ll notice that the steps and how-tos are straight-to-the-point and are written in a language you understand.

Documentation is part of everyday life; for it to make sense, it must be concise.

Here, I’ll explain what Concise Documentation is and its benefits and walk you through the steps of creating one. Let’s dive in.

Benefits of Concise Documentation

Here are some of the benefits of writing concise documentation:

Simple to consume
A study by the Nielsen Norman Group reveals that most people only read about 20% of words on a web page, and they go further to read if the text is clear, the words and sentences are simple, and the information is easy to understand. This highlights the importance of writing concisely, ensuring the information you are trying to pass is well understood and can be located quickly.

This makes the content appear less intimidating
At first glance, complex documentation overwhelms the reader before they can go through it. Writing concisely breaks down concepts into bite-sized instructions that can be quickly followed.

User-friendly content
Let’s say you’re trying to set up a new piece of software on your computer. You have a manual that’s 50 pages long, with lots of technical jargon and confusing instructions. You’re unsure where to start or how to complete the installation process.

Now imagine you have a concise version of the manual, which has been carefully written to be user-friendly. The instructions are clear and easy to understand, with step-by-step guidance that includes helpful graphics and illustrations.

The concise manual makes the content user-friendly and the software installation process easy without any confusion.

Saves time in navigation
Spending hours trying to find a solution or information in a document can be avoided with concise documentation. The format and structure of concise documentation, like clear headings and subheadings, enable readers to navigate it, saving time and effort.

Steps to Create a Concise Documentation

I’ve talked about the benefits of concise documentation. Now let’s talk about how to write concise documentation. Here are the steps to follow:

Determine your target audience
Who will read this? What information are they looking for? What is their level of technical know-how? Why are they accessing it? These are questions to answer before starting your documentation.

The people using your documentation are your target audience; you must ensure they can easily understand it.

For example, you’re writing a user guide for a new video game. The people who will be using your user guide are the target audience.

To determine your target audience, think about who will be using your documentation and their needs and interests. This can involve doing research, such as looking at demographics or conducting surveys to understand better who your audience is.

By understanding your target audience, you can create documentation tailored to their needs, which is more likely to be effective in helping them understand the information you are presenting.

Use simple language
When creating documentation, it’s important to use simple language so your target audience can easily understand what you’re trying to say. This means using words and phrases that are easy to comprehend and avoiding complicated or technical jargon that might confuse your audience.

For example, if you’re creating a user guide for a new software program, you can use simple language to describe how to perform specific tasks. Instead of using technical terms like “algorithm” or “syntax”, you might use simpler terms like “steps” or “instructions” to make it easier to follow along.

To use simple language, you can write in short sentences and break up long text into small, easy-to-digest chunks.

Keep it simple to navigate
The acronym KISS, which stands for – Keep It Simple Stupid – is a useful reminder to keep things straightforward when creating documentation. It’s good advice to strive for simplicity when communicating complex ideas or information to others.

Keeping your documentation simple to navigate means organizing your content to make it easy for others to find what they’re looking for.

This can be done by:

Using hyperlinks to help quickly jump to related sections or external resources.
Adding a Table of Contents or an index so they can locate specific information. This is useful if your documentation is lengthy or covers many topics.

The usability of your documentation needs to be simple to navigate.

Use bullet points
It’s important to make your documentation easy to follow through. This can be done by using a bullet point.

Bullet points are small, circular symbols that precede each item in a list. They are a great way to present information in a concise and organized manner.

Here are some reasons why bullet points are useful:

They help to prioritize information: You can use bullet points to highlight important information or to create a hierarchy of information. This helps your readers to understand the relative importance of each item on your list.
They break up long paragraphs: Large blocks of text can be daunting and difficult to read. By using bullet points, you can break up long paragraphs into smaller, more manageable pieces.
They make information easy to scan: Bullet points allow readers to quickly and easily scan your content to find the necessary information.

When using bullet points, it’s important to keep them short and to the point. Each point should be brief and easy to understand.

Include a tree structure (headings and subheadings)
A tree structure organizes information into a hierarchical or branching structure, similar to a tree with a main trunk with many branches. In documentation or writing, this means breaking down the content into main sections or headings and then further dividing those sections into subheadings or subsections.

For example, let’s say you’re creating a document about different types of animals. You might use a heading like “Mammals” to group together information about animals that have fur and nurse their young. Underneath the “Mammals” heading, you could use subheadings like “Cats,” “Dogs,” and “Horses” to further organize the information.

Using a tree structure helps to break up the text into manageable chunks so that people don’t get overwhelmed by a big block of writing.

Consider how to break it down into different sections using headings and subheadings.

Make use of illustrations and graphics
When explaining something complex or technical, use pictures or diagrams to show what you mean. That’s where illustrations and graphics come in!

Illustrations are drawings or pictures that help to explain a concept or idea. Graphics are visual representations of data, such as charts or graphs, that show information in a way that’s easy to understand.

For example, suppose you were creating a user manual for a new computer game. In that case, include illustrations of the game’s interface to show the player where different buttons and options are located. You could also include graphics that show the player’s progress through the game or their score.

By using illustrations and graphics, you can make your documentation more engaging and easier to understand. Visual aids help break up the text and make it less intimidating, encouraging people to read and engage with your documentation.

It can also help to make your documentation more accessible to people who learn better through visual aids.

If you’re creating your illustrations or graphics, many tools available online can help you create professional-looking images. You can also find free images online that you can use in your documentation. Just credit the original creator and check that you have permission to use the image.

Conduct a peer review

As you work on your documentation, it’s crucial to have someone else review your writing to ensure it’s concise. This is where peer review comes in – it involves asking someone you trust, like a friend or coworker, to read through what you’ve written and give you suggestions on how to improve it.

The reviewer can provide feedback on various aspects, such as:

The clarity and coherence of your writing.
Any errors or typos that need to be corrected.
If your writing is appropriately tailored for your intended audience.

Once you’ve received feedback from your peer reviewer, you can use their suggestions to improve your writing.

When you conduct a peer review, it’s important to choose someone you trust to give you honest feedback and who knows the subject you’re writing about. You can also return the favor by offering to review their writing in exchange!

Check out the best practices and examples of concise documentation - here

A Quality Checklist for API Documentation

Aakhil Karthikkeyan — Wed, 15 Mar 2023 13:46:31 +0000

You know what an API is, particularly what a REST API looks like.

Here, we will be relating to REST APIs.

There are a variety of tools that help automate API documentation such as Postman or Swagger. You still need to “flesh it out” the generated documentation to make it both useful and readable.

REST API documentation is typically split into two major sections:

1. An introductory section that includes for example,

The purpose of the API
Any prerequisites such as setup considerations (including API key requirements)
The base URL to use
Paging considerations for APIs with a large amount of output
Result codes (the most common being 200 – success and 40x – errors of various types)

2. The API itself.

The API may be split into several major functionality groups each having their own endpoint and calls (GET, POST, PUT, PATCH, DELETE etc).

Each call typically requires two tables, one explaining the query parameters and a second for the results. The request parameters may be entered directly, or through an input JSON file. They are described in the first table. Very often the results come in a JSON file the fields of which are described in the second table.

Following the request/results section, add a return codes section. Always show the 200 and 400 return codes. If other possible return codes are standard, then a cross reference to the Common return codes will do. If you are using call specific return codes, add them here.

And finally, provide an example. Many modern API documentation pages have a vertical bar to the right that shows a sample of the API call in a choice of multiple formats (cURL, PHP, JavaScript etc). Other possibilities are a horizontal code bar below the API description or a link to an API sandbox. If for some reason, these features are not available, then at least, add a textbox with a hard coded example.

And there is room for flexibility: A call with a single simple parameter obviously does not need the first table. Similarly, the second table will not generally be required for POST and PUT calls.

Take a look at some of these API documentation examples:

Twitter API

Dropbox API

YouTube API

A deeper look into - API documentation checklist

A Practical Guide to Create Technical Specification Document with Examples

Aakhil Karthikkeyan — Wed, 15 Mar 2023 11:39:54 +0000

“Despite the known importance of a technical specification document, many teams struggle with creating and managing one” – Anna Thornton.

Imagine you have an incredible idea for a new software or engineering design. You have the team in place, the funding secured, and you’re eager to start coding. The excitement is palpable as you discuss features, designs, and timelines. However, amidst all the enthusiasm, it’s easy to overlook an essential step that can make or break your project: creating a technical specification document.

Skipping this step and jumping straight into coding may seem like a time-saver, but it can lead to confusion, wasted time, and a subpar final product. In this article, we’ll explore the importance of technical specification documents and their benefits and provide examples and tips on creating one effectively. So, let’s get started right to it.

What is a technical specification document?

A technical specification document is a technical design document, software design document, or engineering design document is a detailed plan that outlines a software development project’s requirements, objectives, and constraints. It serves as a roadmap that guides the team in building the product, ensuring everyone is on the same page and working towards a common goal.

The technical specification document typically includes the

Functional and non-functional requirements of the software
Scope of the project
Timeline
Internal standards
Impact
Work involved
Budget

It may also include diagrams, mockups, and other visual aids to help the team understand the project’s scope and details.

Technical Specification vs. Functional Specification: Understanding the Difference

Regarding software development, two types of specifications often come up: technical and functional. While they may sound similar, they serve different purposes.

A functional specification outlines the software’s features and functionality from a user’s perspective. In contrast, a technical specification focuses on the technical details such as hardware and software requirements, data architecture, and programming languages used.

In other words, the functional specification answers the “what” of the software, while the technical specification answers the “how.” Both documents are essential for a successful software development project, and they should be written with care to ensure everyone on the team understands the project’s objectives and requirements.

Types of Technical Specification Document

IT Technical Specification

IT technical specification addresses technical projects, IT infrastructure issues, and system updates for the IT team. This document type is commonly used in IT infrastructure projects, such as server upgrades, network installations, and software implementations.

Some details in an IT technical specification document include hardware and software specifications, network requirements, security protocols, and data migration strategies.

Website Technical Specification
The website technical specification outlines the technical requirements for developing a website. It covers aspects such as design, functionality, and user experience. It describes the website architecture, design elements, functionality, content management system, and third-party integrations providing a clear roadmap for the project team.

Software Technical Specification
This gives clarity to any software development project. It describes the software application’s technical requirements, including the software architecture, programming languages, database schema, and user interface design.

In addition, it should describe any external systems or services that the software application will interact with and how it will integrate with them. It should also outline the software development process, including coding standards, testing metrics and requirements, and version control procedures.

Agile Technical Specification
This flexible and adaptable document outlines the technical requirements for each iteration or sprint in Agile development. Unlike traditional technical specification documents, it is created and updated incrementally throughout the software project development process. The document is lightweight, includes a description of technical requirements, and reflects the Agile principles of simplicity and adaptability. It is critical to ensure the development team clearly understands technical requirements and roles, providing a roadmap for delivering working software that meets customer needs.

Product Technical Specification
It serves as a blueprint for a product, outlining its general specifications and intended uses. It includes a product summary, a description of features and functionality, technical specifications, and design requirements. The document can guide the design and development processes, make revisions based on user testing and customer input, and ensure the final product meets user needs and expectations.

It is advisable to use tables and charts to make it clearer and more understandable for the design and product team members.

Equipment Technical Specification
This specification provides detailed information about the technical aspects of equipment, including manufacturing, power requirements, and safety considerations. It helps ensure the safe and efficient operation of equipment. The document typically includes information about equipment dimensions, materials, maintenance and repair procedures, and training or certification requirements.

Technical Design Specification
This specification outlines the details of a product’s design and the technical requirements for its development. It is a roadmap for engineers and developers to follow during the design and implementation phase. The document specifies the technical attributes and requirements of the product, including the tools, technologies, and programming languages that will be used. It also describes the intended user experience, including the product’s features and functionality.

Why do we need a technical specification document?

The advantages of a technical specification document for engineers, teams, and the project itself are numerous.

For Engineers
A technical specification document acts as a detailed roadmap for engineers when designing and carrying out a project. Providing a clear understanding of what is anticipated and outlining the technical requirements takes the uncertainty out of the development process and ensures its effectiveness.

A technical specification document gives engineers a well-specified backup plan, reducing the likelihood of failure. It helps to ensure that everything is planned out, that developers grasp the requirements clearly, and that they adhere to the plan.

For the Team
A technical specification document is a communication tool for teams that helps to keep everyone on the same page and focused on the same objectives. It gives everyone on the team a shared understanding of the project requirements, facilitating communication and information sharing.

For the Project
A technical specification document (TSD) aids in the project’s success. The document reduces the risk of project failure by outlining the technical requirements in precise detail. Lowering the possibility of mistakes, misunderstandings, and lost work, TSD ensures that the project is finished on schedule and under budget.

TSD can also result in long-term cost savings. The project is cheaper and quicker by removing time-wasting during integration and shortening the development cycle. Additionally, ensuring that the infrastructure is built in a way that it can be quickly scaled up or down as necessary makes it easier to scale the project in terms of team size and product scalability.

Things to consider before writing technical specification

Before diving straight into writing technical specifications, there are some things to consider – some questions you must answer.

Question 1: Who is the software/app/project for?
Is it for your current customers, consumers, and users, or your future users and customers? Is it strictly for your employees? You need to answer these questions.

Question 2: What tasks or problems would the app/software/project solve?
Is the product designed for users, and what would they be able to do with it – book a service, order a product, or get updates? If it is for your employees, how would the product improve or increase their efficiency at work?

Question 3: On what platforms can the solution be accessible?
Smartphones, desktops, or laptops? iOs, Android, or Windows?

Question 4: What is the deadline?
Setting a deadline is very important. Set the date and time when you want the app or solution to be rolled out for usage.

Question 5: What is your budget for the project?
You should set an amount of money to spend on the project and how much should be put into different project development sectors.

Once you have all these things covered for your TSD, it’s time to kick off the practical aspect of technical specification documentation – creating it.

How to Create a technical specification document

While writing has many approaches, technical specification writing requires technical skills. To excel in creating a good technical specification document, you need to do the following:

Gather existing information in the problem domain before starting the technical specification document
Read product/feature requirements and technical requirements/standards related to the project
State the problem in detail and brainstorm solutions
Pick the most reasonable solution
Consult with an experienced engineer and explain the problem and proposed solution
Gather feedback and ask for their review of the technical spec
Block off time to write the first draft of the technical spec
You can use a collaborative document editor and a technical spec template to write a rough draft

Once all the necessary information is gathered, it is time to venture into the writing phase. Here are the key sections of your technical specification document:

The Front Page
Brief Summary
The Solutions
Further consideration
Risk, security, and privacy
Impact assessment
Timelines & Milestones
Open Question
Conclusion

Let’s take a quick look at each of them.

Click here to read more

Practical guide to launching a new public API for your company

Aakhil Karthikkeyan — Thu, 16 Feb 2023 12:10:28 +0000

In this digital world, most software applications are delivered through the SaaS model whereby the applications are accessed via a web browser rather than a desktop client. Customers interact with the SaaS application through a front end and undertake value-added activities. The Application Programming Interface (API) helps a company to unlock the full potential of its software suites. The public APIs help the company to integrate its software with other software tools that your customer might use for other purposes. These API-based integrations build a trust factor with your customers that your software application can help them with data exchange with other applications.

The public APIs also help customers automate many mundane tasks in their applications. Once software applications are bought, customers build a lot of business processes around them to undertake value-added activities. These mundane tasks can be automated easily using an API. There are third-party workflow automation tools such as Zapier, Make, Workato, and so on that can be used to automate day-to-day repetitive activities.

The company’s public APIs also help with the expansion of software services. The company’s business partners would be interested in expanding product capabilities using your company’s APIs. The public APIs come without bells and whistles offering a vanilla flavour that provides a plethora of opportunities for business partners to build new things. This also means that the whole ecosystem can be built around public APIs. The ecosystem strives for new functionalities of your public APIs thus setting the stage for continuous product innovation.

Top six key considerations while launching public API

Building a public APIs is a strategic investment for a company. The company shall continue to invest to increase the popularity of its APIs, provide a detailed documentation and enhances usability over time. The below are key things to consider.

Understanding developer needs
Understanding developer needs is a rudimentary activity to kickstart the development of a public API. The APIs should be versatile to developer requirements and offer a rich set of data exchanges. The APIs should be developer friendly and must be very easy to use. The other basic things for developers are.

Solid API documentation
The public APIs shall be supported with good API documentation that helps developers understand the structure of the APIs and explore its documentation on input and responses.
Try-it-out functionality
Alongside the API documentation, the company shall provide some “Try-it” functionalities such that developers can try out the APIs by changing various parameters and being able to see the responses. This helps developers to build familiarity with the APIs and understand their functionality.
Code samples
Providing code samples in popular programming languages helps developers copy a code sample and integrate them in their software applications quickly. This helps with minimizing the “Time to Value” business metric.

Building an ecosystem around your product

Building an ecosystem around your software suites is essential to maximize the value delivery and more importantly for the survival of the software application from emerging competitor threats. Ecosystem helps your company to appeal to a wide network of business partners who are willing to build apps utilizing your company’s public APIs. This makes the ecosystem grow and customers’ ability to extend your software application for other business needs. The ecosystem involves either building a marketplace or offering connectors. Companies such as WordPress, Shopify, Freshworks, and so on build a good ecosystem around their products by making their company’s API public.

Security

While building public APIs, the security aspect of an API is paramount. The APIs shall be accessed via secured HTTP protocol and offer enterprise-grade security for API authentication. In addition to this, the company should have a secure way of helping developer to get API authentical tokens. The company’s public APIs should comply with industry security standards and adopt best practices to win the developer’s trust. The more investment is being made into API security; the developers’ trust will grow as it mitigate emerging cyber security threats.

API usage
The public APIs should have rate limits depending on the subscription plan to ensure that developers interact with APIs at a specified limit. The company should also have a good fair usage policy to ensure that some developers are not sending too many requests to the API servers which harms everyone! Technical customer support should be available for developers to help with troubleshooting any API-related issues. This shows how much a company is invested in making its public APIs successful.

Developer portal
A developer portal can be set up if the company wishes to scale its APIs offering. A developer portal provides a holistic view to help developers access API documentation, try-out APIs, interact with other developers, understand business use cases, promote customer success stories, get technical help, and much more. A developer portal can also be a test bench for the release of new APIs. Mock servers can be set up to emulate the real-time environment in which developers can try out new APIs and explore new functionalities.

Continuous innovation
Without innovation, growth stalls. The company shall invest in upgrading existing APIs and offering new APIs as part of its product innovation. This means releasing new API versions periodically and deprecating old versions over time. This ensures that your software application is aligned with customer behaviours and technology trends. Many companies have moved to offer GraphQL as part of their API offering which helps developers to get more data in one API call rather than making multiple API calls in the old paradigm. Adopting new technology in offering APIs reduces development time thus enabling business partners to be more agile toward change.

Steps to launch a new public APIs

Once the key considerations are addressed, the below are the simple steps to launch a public API.
Ensure that API documentation site is available with “Try-it” features and code samples.
Announce the new API via product release notes and notify existing customers through the software application.
Promote the new APIs through your business partners and other social media channels.
Release your APIs in a prominent developer conference and get developers excited about new use cases.
Publish customer success stories in your company’s website to show how new APIs have created successful business outcomes.

Wrapping Up

It is a very important milestone for a company as it releases public APIs for the suite of software applications. This promotes business partners with product integrations. The solution integrators can also make use of public APIs to build a technology stack to their client’s requirements. The company’s public APIs also help to flourish rich ecosystems. Developer communities thrive on ecosystem builders to build new things and offer new services. To sustain the developers’ interest in your company’s API, continuous innovation into API is essential. Thus, opening the API makes the company a prominent player in their market segment.

7 Best Alternatives To MadCap Flare

Aakhil Karthikkeyan — Thu, 16 Feb 2023 09:51:22 +0000

Many technical writers and developers are concerned with creating technical documentation for their users. These content creators want to teach customers how to use their product, comply with regulations, and help them seek assistance when they run into trouble.

And when you have a large volume of content to create, you’ll want to seek the assistance of a help authoring tool (HAT).

MadCap Flare is one such solution. Why do users like Flare? Because it has a plethora of useful features that help you single source your content. At the same time, Flare is very complicated and requires an advanced learning curve. For these reasons and more, we’ll discuss the seven best alternatives to Flare in this article.

What is a Help Authoring Tool?

A Help Authoring Tool lets you create, manage and distribute content for the purpose of helping your users. It enables different authors to collaborate on content and distribute it on various mediums. It’s often possible to import previous documentation from other tools and work with it in your new HAT.

HATs make it easy to work with large amounts of content and publish your documents to a professional-looking format.

Some of the basic features that a HAT must offer is:

Editor for working with text or code
Analytics for assessing how customers are interacting with your documentation
Single source authoring for documentation in different formats
Review process for collaborating on documents
Capabilities for working with images, video and audio
Customization to fit your brand

What does MadCap Offer?

MadCap Flare offers the capabilities to single source your documentation and publish to different formats. Topic-based and micro-content authoring gives creators ultimate control when it comes to managing and distributing their documents. Your problem when using Flare may not be what it can do, but how exactly to utilize its features to best support your documentation efforts.

Content Development
Flare gives you many ways to manipulate your content, allowing you to create technical documentation, application programming interface or API documentation, software documentation, interactive eLearning courses, learning and development programs and much more. The ribbon toolbar mimics Microsoft Word, giving users an interface that they will be familiar with.

Multichannel Publishing
Flare users can create content once, and then publish instantly to a number of different channels. You can update content in a single location and then re-publish to your preferred formats, giving users a consistent experience and minimizing re-work. This feature also allows you to cater your documentation to different audiences, such as beginner and advanced users.

Project Management
With Flare, you can easily manage documentation projects from beginning to end. Flare allows you to keep track of your progress, and lets you see all items relating to your project at a glance. Project templates allow you to create beautiful web and print-based outputs in minutes.

Collaboration
Your team can contribute to and review documentation directly within the cloud. Contributors don’t need access to the whole of MadCap Flare to review documents and get them ready for publication. Flare keeps track of changes made so you can stay up-to-date with different versions of your documentation. Changes can be made simultaneously so you don’t need to worry about version conflicts.

Translation
MadCap Flare gives you the capabilities to translate your documentation into multiple different languages. Flare supports Unicode language characters, double-byte Asian languages and Eastern European languages, as well as bi-directional language authoring and publishing including Hebrew, Arabic and Persian. Integration with MadCap Lingo gives you support for the translation process.

Hosting and Development
With Flare, you can host your documentation on your own servers to give you unparalleled control over the security of your documentation. You can also use MadCap Flare to securely host your web-based documentation without the need for IT resources.

Analytics
MadCap Flare does come with some capabilities for analytics with real-time end-user statistics. It shows you how users interact with and find your content, so you can improve overall content quality. You can run tests before you publish to identify critical technical issues.

XML Editor
The XML editor is the primary editor used for topic-based authoring as well as snippets. Flare does not require you to know anything about XML in order to be able to use it. For example, it allows you to fix broken links without opening the file in Flare.

On-premise and Cloud Application
Flare can either be used on-premise or through the cloud. The cloud version of Flare offers slightly limited features when compared with the on-premise solution. On-premise could be preferable because it doesn’t rely on accessing an internet connection to work with Flare. Bearing in mind Flare deploys your documentation with secure hosting through the cloud.

Preview Option Available for Multiple Outputs
Before you publish to your outputs, Flare gives you the option to preview your content before you deploy to web, print, tablet and mobile. You don’t need to publish your documentation to see what it looks like using the WYSIWYG editor to preview content.

Style Sheet Customization
Flare uses HTML and CSS to customize documentation before it is published. Flare requires in-depth knowledge of CSS in order for users to present their documentation for final publication.

Limitations of MadCap Flare

Despite being a fantastic tool for help authoring, Flare has some significant shortcomings, let’s discuss it.

Limited Search Feature
The search feature in MadCap Flare may be slow, especially when searching large amounts of content. This can be frustrating for users and impact the overall user experience. Also, the search feature in MadCap Flare may not always return complete results, especially when searching for complex phrases or combinations of terms. Another limitation is that MadCap Flare search function may not always behave consistently across different projects or documentation sets, making it difficult for users to understand how the search feature works and how to use it effectively.

No Markdown Editor
Flare doesn’t offer a native Markdown editor which means you can’t create your documentation in the most popular language used by developers.

Home Page Designer
Flare offers limited functionality for customizations from its home page designer, meaning you can’t tailor your documentation for your particular brand. Your Flare documentation sites are likely to look very similar to other users who are taking advantage of Flare.

Feedback Manager
There is no option in Flare to capture feedback from the users of your documentation. You are unable to understand the quality of articles and which are most useful to your end users.

Notifications
In Flare, notifications can be sent to Slack/ Teams. However, Flare has limitations to number of events that can be sent as a notification. Flare notifications offer updates on users, teams and projects. Granular notifications for each activities cannot be set

Redirect Rules
There are no capabilities in Flare to redirect your former pages to new articles in your documentation site. This means your URLs will break if you move to a new location.

Ticket Deflector
Flare can’t tell you how many tickets have been deflected by your knowledge base that would formerly have been directed to your support team. You don’t know which customers have chosen your documentation over submitting a support ticket.

Fairly Steep Learning Curve
Flare requires knowledge of HTML and CSS in order to use its functions. It’s aimed at deeply technical teams and may not be suitable for those who want to produce simple documentation.

Top 7 MadCap Flare Alternatives

Document360
If you want a much simpler alternative to MadCap Flare, then look no further than Document360. Document360 is a help authoring tool that allows you to create documentation in HTML or Markdown to build an engaging knowledge base for your users. Document360 makes it easy to collaborate with other authors and review content to get it ready for production.

Most help authoring tools take days to get up and running. Document360 is functional within minutes and you can create beautiful help sites for your users. Document360 sets itself apart by having a Markdown editor that you can use to create your documentation, alongside the WYSIWYG editor which means both developers and non-technical team members will be comfortable using it.

With Document360, you have the capabilities to analyze your documentation and make sure it is up to scratch. You can find out who your users are and what they require from your documentation. Document360 gives you powerful imports from multiple tools which makes it easy to deploy your new documentation site.

Document360 gives you the opportunity to review who is making changes to your content. You can compare versions of different articles to make sure you’re on top of the latest changes, and revert back to previous versions if necessary. The user groups comes from technical writers, documentation experts to product managers who can work easily and effectively avoiding complexities.

Document360 integrates with many third-party applications and services, making it easy for users to manage their documentation. These integrations allow users to utilize documentation with an external application such as Slack, Microsoft Teams, Intercom, Zapier, Salesforce, Zendesk, Freshdesk, and more. Additionally, you can integrate with any product using JavaScript Snippet.

Adobe RoboHelp
RoboHelp is Adobe’s answer to MadCap Flare, a help authoring tool for technical content that will improve the productivity of your authors and compliance for online help, policy and procedure, knowledge base, and self-service content. With RoboHelp, you will definitely need to know HTML and CSS as this is used for designing all your help content. It enables single-sourcing of content so you can create content once and then reuse it across all your channels. You have the option to create microcontent that will fuel chatbots and claim the featured snippet in search engines.

Clickhelp
ClickHelp is an good option for companies looking for a new help authoring tool. ClickHelp is an up-to-date cloud-based documentation platform for teams who want to create, host, and maintain online software guides, knowledge bases, context help, and instructions. ClickHelp lets you to collaborate effectively with subject matter experts using the online portal, and publish documentation to a range of web-based outputs. It’s not too complicated to set up and integrates with all your favorite tools such as Google Analytics, Zendesk and YouTube. The users can export content to different file types including CHM, PDF, RTF, or EPUB.

Click here for more alternative options for madcap flare

What is API Developer Portal with Best Practices & Examples

Aakhil Karthikkeyan — Wed, 25 Jan 2023 06:09:16 +0000

What is a DevPortal?

According to Provonix, a primary sponsor of the DevPortal Awards, the definition of a developer portal is as follows:

“A developer portal – often shortened to DevPortal – is the interface between a set of APIs, SDKs, or other interactive digital tools and their various stakeholders.”

Said more plainly, developer portals are websites that provide interfaces for all services and solutions offered by a company. They are a resource for many kinds of stakeholders, not just developers.

A key difference between a normal website and a DevPortal is that normal websites contain static content while DevPortals contain dynamic content that is constantly being updated.

Developer portals, unlike wikis, are external while also acting as a resource for internal stakeholders. Since wikis are internal, they are often neglected and become out of date as priorities shift away from the documentation. Since developer portals are external, their maintenance is often a higher priority than internal wikis.

Surveys have stressed the importance of high-quality developer documentation. A survey in SmartBear’s The State of API 2019 Report ranked “Accurate and Detailed documentation” third place for the top characteristics of an API. DevPortals are the primary way SaaS companies share documentation.

There is also a blurry relationship between DevPortals and marketing websites. Sometimes an enterprise will have a marketing website that links to its DevPortal. Other companies, like SaaS-only companies, will have DevPortals and no dedicated marketing website.

What is the significance of a DevPortal?

So, why should a company invest time and money into enhancing its DevPortal? A good developer portal conveys the value of a platform and its services. It describes how it solves specific business challenges without using marketing/advertising hyperbole.

While API documentation is often associated with developer portals, a DevPortal is not just a place where developers access their API reference documentation. The DevPortal should allow all business stakeholders (technical or non-technical) to learn about and experience a platform.

In the next section, we will explore these characteristics.

What makes a good DevPortal?

The following are characteristics of an effective DevPortal.

Unifies solutions
While API documentation is an important aspect of a DevPortal, it is not the be-all and end-all. Developer portals ideally act as a central resource for all interfaces to a company’s products and services. They may not be limited to just APIs / services. Other interfaces include GUIs, no-code interfaces, and low-code interfaces like widgets for users without access to developer resources.

While REST APIs are a focus of developer portals, other kinds of APIs can be documented such as Internet of Things (IoT) APIs, voice assistant APIs, GraphQL APIs, or native library APIs. Oftentimes a company will have a range of services, not just a REST API. It is possible to see dozens of APIs of different types documented on a DevPortal. Other technical solutions made available on DevPortals besides APIs are client libraries or SDKs. Sometimes a DevPortal can also showcase solutions built by developers

Clear business model
The user should be able to understand the platform industry and a broad overview of the services it offers. Solutions should be categorized by area or specific business challenges they solve. The user should be able to develop a mental map of all solutions on offer and how they fit together in a unified platform.

How services relate to each other in the bigger context can be communicated through text, visual graphics, or the structure of the developer portal itself.

Up-front pricing
The customer should understand a platform’s pricing model very early on. The pricing structure should communicate how it solves particular problems and the differences between the pricing plans.

The DevPortal should answer questions like:

How are the API products monetized (direct vs. indirect)?
What are the differences between the available pricing plans? Are there plans for pay-as-you-go, self-service, or freemium?
Are they any rate limiting restriction per pricing plan?

Pricing plans relate to the onboarding process because users are often allowed a limited number of features before they must pay. Transparent pricing facilitates the transition from a potential customer to an actual customer.

Content “layering”
Layered architecture is a concept borrowed from software development that can be applied to content organization.

Here is an example of how a DevPortal can be layered:

The top layer of a developer portal would be the landing page the user understands the business model, an overview of services/solutions offered, and common use cases.
The middle layer would be the solution categories that group solutions according to the business challenges they solve.
The bottom layer would be the documentation for those solutions, including any getting-started tutorials and API references.

Of course, these are only examples. Other layers may be necessary depending on the business.

A layered architecture allows for consistency across solutions. The user learns what information to expect from each section.

Similar to the main landing page, each solution should have its landing page that communicates the value of the solution. A solution page provides quick access to the solution overview, use cases, onboarding details, getting started, and technical reference material.

Using a layered architecture that separates the different components of the platform allows for extensive use of linking. You can link to technical sections from business sections, and vice versa. For example, a business analyst that reads solution overviews may only want to view business information while also having the ability to learn more by clicking a link to the technical documentation. Linking also allows developers to jump to technical details rather than being stuck reading business material.

Consistent design
Design elements, when done correctly, go beyond aesthetics. Design elements promote usability and go together with the quality of the content. A well-designed developer portal has design elements that support the user journey as they discover, learn about, and interact with a platform.

An effective design reinforces the overall brand. A brand not only determines the aesthetic choice but also how the content is written. Documentation should be written using the same style and tone with consistency across all solutions.

Findability
How easily the user can discover the solution to their business challenge is the primary aim of a DevPortal. The process of finding information on a DevPortal should be frictionless.

The “findability” of information in the developer portal is determined by its structure and search/filtering capabilities. DevPortals should structure their documentation portals so users can easily see the range of solutions available. It should be easy to filter solutions by category to narrow down the list of possibilities and remove noise.

From within the API reference, you should be able to search and filter by resources, endpoints, parameters, and schemas.

Caters to non-technical users
SaaS companies also understand there are different ways to consume a technical product besides building an app that leverages a service from the ground up. For example, a platform may provide widgets you can easily add to your website with minimal coding. No-code or low-code solutions break down the barriers to who can experience the value of the technical product.

The best DevPortals have onboarding journeys for each competency level. For example, a technical user can build an app from scratch whereas a non-technical user can download a template to begin experimenting with.

Onboarding
The onboarding process is usually a user’s first experience using a solution. If there is friction in the onboarding process, a prospective customer may give up before fully demoing the API. After setting up your account and retrieving credentials, the Get Started section walks the user through an end-to-end process of interacting with the solution, such as an API.

API Reference
An API reference is a concise and detailed guide read by developers to understand an API. Effective API reference pages allow developers to quickly locate information for resources, endpoints, fields, or schemas using a combination of searching and filtering.

A try-it-out feature provides a hands-on way of interacting with an API. The most advanced DevPortals automatically populate try-it-out widgets with a user’s credentials based on their account details.

Community
Community is often first-level support for troubleshooting issues. Many dev portals have community pages. Some companies use tools like Discord channels or public Slack channels to host discussions under different categories.

If a user can find an answer by posting a question to a message board, they do not need to contact support. If a company is involved in the community, it can log the issue as either a bug or documentation improvement.

Communities can go beyond just discussion forums. They can lead to small meetings or large conferences that promote a platform.

Updates
Regularly posting updates as a platform evolves is a signal for reliability and trustworthiness. Release notes, statutes, and changelogs are all examples of supplemental documentation that keep the user informed of the latest changes

DevPortal Best Practices

There are many steps to building a DevPortal before any line of code is written. Assuming the business model is solid, developer experience (DX) design should be conducted to align all aspects of the portal to provide the best experience to users.

Clarify business model
The structure of the DevPortal should reflect the structure of the business and its solutions. The user will be lost if a DevPortal does not communicate the business structure well.

Keeping the portal up-to-date requires collaboration across the organization and will not succeed by relying on one team. All teams are responsible for keeping their domain up-to-date and responsive to feedback.

Conduct Developer Experience (DX) design
Developer portals are closely related to the concept of Developer experience (DX). Unlike normal User Experience design, DX is tailored to developers who use technical products often without a GUI like APIs, client libraries, or SDKs. Since there are no user interfaces, documentation must tell the developer how to interface with the product. Documentation to a large extent plays an important role in how a developer or other business stakeholder “experiences” a technical product.

In the same way, companies hire UX designers, they should hire DX designers to craft the experience of developers using the DevPortal. A DX “strategist” is a central role to manage the lifecycle of the developer portal. The DX strategist oversees changes to processes, standards, and tooling that flow out to individual solutions teams. This strategist ensures the design, aesthetics, structure, and content work together to create a pleasing experience for the developer.

The strategist creates the personas of the people visiting the portal and crafts user journeys to meet their needs. For example, there would ideally be separate onboarding user journeys for technical users and non-technical users.

Structure the portal
When establishing the information architecture, you must determine which information is required across all solutions. For example, each solution requires onboarding, use cases, and API reference in a particular order. If documentation is uniform across solutions, the DevPortal user knows what to expect.

A layered architecture, coupled with linking, will make navigating from the top layer (business details) to the bottom layer (technical details) easier, and vice versa.

Establish governance program
Many times, each solution is managed by a separate team. To provide a consistent experience across the portal, standards must be established that promote the consistent organization of content and writing guidelines.

Establishing a governance program requires collaboration to develop standards as well as buy-in from the separate business units to fully complete the program. Each team should be responsible for adhering to these standards and held accountable. A governance program should align language and tone, style and formatting, and organization of content from business material to API reference. Finally, a governance program should reinforce branding.

Reduce the learning curve through onboarding
After communicating the value of the business as a whole, the user should be immediately guided toward separate solution pages where they can try out APIs, services, client libraries, or SDKs. The front and center of these pages should be a link to onboarding procedures so they can experience the product as soon as possible.

For the Get Started tutorial, pick a simple use case that the user can follow to understand the solution from start to finish.

Properly document API reference
Are all the API components accurately documented? Is each resource documented? Are individual endpoints and schemas described fully? Does every field description state its purpose, the effect of chosen values, and interactions with other fields in the system? Are definitions for the same field standard across the spec? The content of the API reference should follow an API style guide that determines standards for all components of the API. Following a style guide ensures consistent and complete documentation across the API reference. Without accurate and detailed reference information, all the flashy features are useless.

Documenting technical reference information is often the first step to improving overall documentation because the technical information must be solid before writing tutorials.

Configure search / filtering
A DevPortal can have dozens of pages corresponding to separate solutions. Along with a clear site structure, having a robust search can improve discoverability so the user can find the solution that solves their particular business issue.

There should be an API Explorer where the user should be able to search and filter a list of solutions offered.

It is important to have a robust search in API reference docs. The search bar on an API reference should allow for a granular search of all components making up the API.

Establish community
From early on, you should think of ways to foster and grow a community around your business’s solutions. This is both a long-term strategy for support and also for the adoption of your products.

Other subtler forms of community are asking developers to sign up for newsletters that keep the communication line open.

Initiate a feedback loop
There should be many opportunities on a DevPortal for a user to provide feedback. For example, each API reference section provides a rating mechanism with the option to provide free-form feedback.

Another source of feedback is community. A community actively using a product that posts is a source of feedback without even having to ask for it.

Provide case studies and references
Case studies are convincing when they are coupled with testimonials of clients that use the product. Case studies can be common business challenges and how they are solved using a platform. A user may relate to a case study and immediately see how they can use the tool to accomplish a certain task or solve a problem that someone else experienced.

Regularly post updates and statuses
Regularly posting updates as a platform evolves is a signal for reliability and trustworthiness.

Continue reading the full article at Document360

The Documentation Review Process: A Practical Guide

Aakhil Karthikkeyan — Fri, 23 Dec 2022 12:15:28 +0000

When you’re working on a project and have to conduct a documentation review, you might be confused about what exactly this process involves, who are the stakeholders, and the what the outcome of the review process might be. In this blog piece let us scratch the surface of the Document review process and its vitality to quality content.

Definition of Document Review

Documentation review is a process where the document goes through one or multiple stages of review and reviewers and the feedback gets amended in the document. The outcome of the document review process is that it enhances the accuracy and quality of the document.

Documentation review is one of the most time-consuming activities regarding end-user documentation. It requires much concentration and focuses since it’s not as simple as reading through the document and spotting grammatical errors or typos.

In fact, it’s much more complicated than that and requires scrutiny of every word, heading, sentence, and paragraph to ensure that there are no logical inconsistencies or gaps in information. You need to understand the structure of the document, identify the primary audience, evaluate its readability, identify any truncated sentences or sections that should be expanded, etc.

Different Stages of Document Review

Peer review
– The document is reviewed by a relevant to the core content of the document

Editor review
– The document is reviewed by a senior writer, or an editor reviews the document’s for overall quality

Stakeholder review
– The document is reviewed by the Subject matter expert or the end users

Compliance review
– In case the document has to adhere to regulations and compliances set either by the industry, governing body, or the company the document is put through this review as well.

Purpose of the Documentation Review

When you’re conducting a documentation review, the first thing you need to do is determine or understand the purpose of the review. This will determine the criteria you use to evaluate the document during the review and the length of the review.

For example, suppose you’re conducting a review of an internal employee training document. In that case, your primary goal will be to ensure that the document is accurate and that the information is presented in a way that’s both easy to understand and accessible to the employee. The outcome of the document should be that the employee is well-informed of the context after reading the document.

On the other hand, if you’re conducting a user manual review, your primary goal will be to ensure that the document conveys accurate, complete, and consistent information about the product or service to the end user.

For example, Let’s assume you are working on a user manual for an HR portal. You are reviewing an article on how users can reset their login password. In that case, you need to ensure the article contains the complete application process flow leading up to the Login screen, reset password button, and what happens after you have initiated the reset. Also, you must ensure the consistency of the business terms in the article.

Who conducts document reviews?

Document review is done mostly by multiple reviewers and sometimes by a sole reviewer. The reviewers can be both in-house or independently hired reviewers. As far as personnel is concerned in the document review they can be other writers, Subject matter experts (SME), Editors, SEO personnel, or anyone relevant to the document for that matter.

Subject Matter Expert Review

A Subject Matter Expert (SME) can be anybody from your Developer, Engineer, Support manager, Analyst, etc., who has a comprehensive understanding of the core concept of your document.

For example, In a SaaS company, the developer can be considered a Subject matter expert as they develop the feature that the technical writer documents.

The role of the SME in the review process is crucial as they scope out all the technical gaps and inconsistencies in the document. It is not always the case that the document writer would be an expert on the technicalities of a feature compared to technical personnel working on the same product. Hence, Subject matter experts and Technical writers should work hand-in-hand on technical documents or product documentation.

What to Look for During a Documentation Review

When conducting a documentation review, you need to look for several things, including the quality of the writing, the structure of the document, the context provided, the flow of content, and the readability level of the document.

Let’s discuss these aspects in detail.

Quality of the writing – Whether you’re reviewing a user manual or training documentation, the quality of the writing is the first thing to look for when conducting a review. You must ensure that the document is free of grammar, punctuation, and spelling errors. If the document is riddled with these kinds of errors, it will reflect poorly on your organization, especially if it is an end-user document meant for customers. One suggestion to aid you with the review is enforcing a custom or available Document style guide. You can also use third-party grammar check tools such as Grammarly to a certain extent.

Structure of the document – The structure of the document refers to how the information has been organized. If the document has a table of contents, you must review the table of contents and make a note of any inconsistencies. If the document does not have a table of contents, you must identify the primary sections and provide a summary of each section. Usage of the Heading tags (H1, H2, H3…) is highly recommended. Also, the document should follow a set document pattern, the most common being Introduction-Problem Statement-Resolution-Conclusion-References.

For example, Document360 editors (Markdown and WYSIWYG) lets you add Heading tags such as H2, H3, and H4 in your article. The platform also has the ability to autogenerate Table of Contents (TOC) based on the Heading tags provided in the article.

Check here to continue reading this article

How Does a REST API Work with Examples and Challenges

Aakhil Karthikkeyan — Tue, 29 Nov 2022 13:24:25 +0000

API is the abbreviation for Application Programming Interface and is a piece of code that specifies how different software components should interact and communicate programmatically. Many are not aware that, under most modern user interfaces, dozens of requests are being sent to API servers for data. The client then processes data returned by the API server to elicit some outcome in the user interface.

For example, if you have ever searched on an aggregator website for the best deals on flights or hotel bookings, a “request” for data based on your search criteria was made (after clicking the submit button) to an API specializing in flights or bookings. After the aggregator website retrieves the data using the API, the search results are displayed to you.

The aggregator website and its associated databases did not store the data appearing in the search results. Instead, the website sent a request for data matching your search criteria to an external web service (i.e. API). The API returned the requested data to the website, and the website parsed the data and rendered the search results.

What is a REST API?

There are many kinds of APIs. Sufficiently describing all of them here would require many blog posts. For our purposes going forward, we will limit the scope of discussing APIs just to REST APIs.

REST stands for representational state transfer and is a particular kind of architectural style that APIs considered “RESTful” are constrained by and “conform to”.

REST APIs are a very common and important type of API that uses HTTP protocol for data transmission. Since this HTTP protocol is used, a REST API is considered a “web service” that deals with the interaction between client applications and API servers. Using this protocol, a client sends an HTTP request for data to an API Server and then the server sends an HTTP response with encoded data back to the client.

The HTTP protocol used by REST APIs allows for platforms and systems written in different programming languages to interact with one another. For example, a client application written in C# can interact with an API server written in Java. This interoperability between systems makes web services very popular in modern software development, and REST APIs in particular.

REST API Use Cases

REST’s separation of concerns for the client and server makes it attractive for many kinds of projects, whether mobile development, web development, etc.

Here are common use cases:

Cloud applications – REST’s advantage of statelessness (discussed more later) is suited well to cloud applications.
Cloud Computing – REST supports cloud computing in controlling how URLs are decoded during client-server communication.
Microservices – REST APIs connect microservices together into one application.

Anatomy of REST API request

The APIs set the rules for how client applications/backends and API servers can communicate programmatically. The API determines how the client needs to send requests, and what sort of information is returned by the API to the client.

The basic components of REST API requests are discussed below.

Resources
The different kinds of information the client can request from the API are called “resources”. Think of a resource as a type of data object returned by the API.

For example, the well-known Swagger Petstore API consists of several resources, namely: Pet, Store, and User.

All relate to the central theme of the pet store, but each represents the different data objects you can create, manipulate, or delete.

You will notice when reading API documentation that endpoints are grouped under their related resource. For example, the “pet” resource has several related endpoints (discussed soon) to take action on a pet resource. You can create, update, or delete Pets.

To solidify the concept of resources: When you create a Pet, know that the API returns a Pet resource or pet “object” that in some sense represents a physical pet added to the pet store’s system.

Endpoints

If you were to expand either the pet or store resource, you would see various endpoints. Each endpoint does something different.

Endpoints are at the core of API requests and usually stand out in API documentation. Most notably, the method (or action, like POST) of the request and the end path (ex. /pet) of the endpoint are highlighted. The following is a list of endpoints of the pet resource.

When you send a request to an API, you send an HTTP request using the specific “end path” of the endpoint. The end path comes after the API’s base URL. For example, the base path of the Swagger Petstore is https://petstore.swagger.io/v2/, whereas an end path for a pet store endpoint looks like /pet. The full Resource URL used to send a request is https://petstore.swagger.io/v2/pet.

An endpoint can have multiple paths and methods (discussed soon) that elicit different responses from a resource. The request below sends a request using the /pet endpoint with the POST method. POST indicates you wish to create something, in this case, a pet.

The request below sends a request using the same /pet endpoint, except this time you use the GET method to retrieve details of a pet rather than create one. Notice that you need to append the petId of the pet to your request (parameters discussed later).

Methods

As briefly discussed, HTTP methods are sent with API requests to indicate the actions you would like to take toward a resource. There are many API methods, so I will only list some important ones:

POST request – creates a resource.
GET request – retrieves information about a resource.
PUT request – updates or creates a resource.
DELETE request – deletes a resource.

HTTP methods correspond to CRUD Operations. For example, the HTTP methods POST, GET, PUT, and DELETE correspond to create, read, update, and delete CRUD operations.

Parameters

Think of parameters as options or filters passed with an endpoint that affect what information is returned in the response. There are different types of parameters, such as:

Header Parameters – Included in the Request Header of an API request and are usually related to authorization. For example, many times an access token parameter is included in the Request Header that authorizes requests of the client to the API.

Path parameters – Included in the Resource URL of an API request and are indicated by curly braces at the end of an endpoint’s end path. For example GET /pet/{petId}.

Query string parameters – Included in the Resource URL of an API request and appear after a quotation mark (?).

Note that endpoints may or may not use all of these kinds of parameters. However, header parameters are usually included for authorizing requests.

Request Body
Request bodies are essentially JSON objects passed in the body of an API request and are often used with POST or PUT methods. Even though they are not classified as such, they are like parameters that take the form of a JSON object rather than a key-value pair like a normal parameter.

REST’s Core Principles

REST’s core principles are what makes it so attractive in software development.

Client and Server

REST APIs have an architecture designed to separate the client from the server so both can evolve independently. The client is not concerned server’s data storage, and the server is not concerned with the user interface. This separation of concerns makes user interfaces very portable and server elements more scalable.

Statelessness

The statelessness restriction of REST ensures state data is only stored in the client application and not on the server. Every request made by the client is independent of any previous requests and includes all required information. Since the server stores no session-related information, the client application manages its session data.

Cacheable

When a client sends a request to a REST API, the API must indicate that the response either can or cannot be cached. Also, it must indicate how long the client can cache responses. Caching can improve availability and performance by reducing the number of API requests since the client can leverage cached data for a certain duration of time.

Check here to continue reading this article

Agile Documentation: Methodology & Best Practices

Aakhil Karthikkeyan — Thu, 03 Nov 2022 11:51:07 +0000

Since the introduction of the Agile Manifesto, software development has changed its trajectory. Moving from waterfall design to an agile way of building software provided greater business agility to listen and respond to evolving customer needs.

Agile software development laid a solid foundation for technical documentation to change the way technical documentation is produced. One of the core principles in the Agile manifesto is “Working software over comprehensive documentation”. This principle emphasizes two things for technical writers:

Stronger collaboration with the developers’ team to build documentation in line with the software development lifecycle.
Produce a minimum viable documentation that is good enough so that your customers can use that documentation right away.

In this, both software developers and technical writers are aligned to respond to change quickly rather than following a fixed plan. This sets the precedence for technical documentation team organisational structure change, documentation processes, and frameworks that adopt agile principles. Welcome to “Agile Documentation”, a newer way of building software/product documentation that offers business agility and competitive advantage.

What is Agile Documentation?

Agile is a lightweight framework that helps people, teams, and organizations generate value through adaptive solutions for complex problems. Agile documentation refers to the practice of producing documentation following the principles setup in the Agile manifesto. Technical writers work closely with software developers to prepare product documentation at a pace aligned with the developers with sprints.

The technical documentation adapts agile ceremonies including standups, sprint planning, and retrospective. All the learnings are shared amongst the product owner, and product managers. Adapting the principles of the agile manifesto inside the product documentation team supplements product features and provides a complete product experience

Importance of documentation in Agile software development

The agile manifesto lays out fundamental principles of the agile software development process such as

Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan

However, this manifesto leaves the implementation open thus a lot of people have different approaches at the beginning of the agile software movement. A lot of convergence and best practices emerged after a few years of many companies experimenting with agile ways of software development. Customer focus is the central theme of agile manifesto as software is a solution to a customer business problem.

Agile methodology provided relentless focus on customer business requirements and ensures that a Minimum Viable Product is built as a solution. In supporting the agile software solution, documentation should be accompanied with every software release. The importance of agile documentation in the agile software release cycle can be summarised as follows

Software and documentation shall be released simultaneously to maximize customer experience
Agile documentation processes to supplement software developers providing business agility
Documentation team and software developers adopting the same agile methodology and processes helps to get consistent practices across the team
Agile documentation processes set the stage for tighter collaboration with software developers
Agile documentation also helps with reducing time to value for customers to utilize the software solution holistically with accurate documentation
Communicate technical information to your customers such that the product value can be maximized
Compliance / regulatory bodies mandates to have technical documentation as part of their software product

3 Questions to ask while Creating Agile documentation

Creating documentation utilizing agile methodology is an art that can be mastered over a period. There are three important questions you need to ask while creating an agile documentation

1. What documentation to produce?

Figuring out “what” is the preliminary task for a documentation team as the product owner usually communicates “why” to the documentation team and software developers. Experienced agile documentation team usually have a framework for “what” as it depends on what purposes do the documentation serve and what it needs to encapsulate. The famous “what framework” in the agile documentation is Diataxis.  

Diátaxis framework in the agile documentation approach provides a holistic understanding of the needs of documentation users in their cycle of interaction with a software product. Diátaxis framework in the agile documentation lifecycle is easy to apply.

Source

The main questions you need to ask in understanding the “what” in agile documentation are

What documentation will be required before the project begins?

Diátaxis framework helps to answer this question as the type of documentation depends on the purpose it is going to serve. The tutorials, How-to guides, reference materials, and technical explanation requires a different style of writing for their intended audience. This is figured out before the sprint begins

What kind of documentation will be required during the project?

During the agile sprint, the scope of the software development might shift as the customer requirements are still evolving. During the sprint, the documentation team might need to change the documentation that is being produced. Depending upon the scope change or minor amendments to the sprint scope, the type of documentation varies

What kind of documentation will be required once the product has been deployed and implemented?

If the scope of the agile sprint has not been changed, then the final documentation will not see a change since what has been planned will be delivered. However, if the scope of the sprint has changed, then the final documentation after software deployment may look different. In this case, a continuous improvement process is integral to agile documentation

2. Where to keep documentation?

Continue reading the full article at Document360

Ultimate Guide To Create an API Documentation with Examples

Aakhil Karthikkeyan — Fri, 28 Oct 2022 10:39:44 +0000

When you buy a new product it comes with a manual to instruct you in how to use it. You wouldn’t take home and unbox your new games console without expecting there to be a manual for setup, use, and maintenance. When customers don’t know how to use products, they are less likely to be retained by the company or buy other products in the future.

An API (application programming interface) is no different. When you have developers learning how to use an API, they need a set of instructions in order to be successful. Rather than being faced with an abundance of tickets submitted to your support team, documentation offers an interface between your company and end users.

API providers are obligated to supply API documentation that is relevant, specific and fresh, in keeping with the latest developments in your product. It doesn’t matter how good your API is if developers don’t understand how to put it to use.

What is API Documentation?

API documentation is a set of instructions that tells developers and other interested parties how to use your API and its services for a specific end. It usually contains code examples, tutorials, and details about the functions, classes and return types. It essentially provides developers with all the information they need to build integrations with the API and make API calls with the software.

API calls are a type of request that is made by the third-party developer to the platform’s API. The API calls are described in the documentation and tells the developer exactly what they can ask the API to do and how.

API documentation clearly explains its endpoints, interprets why you’d want to use them, and gives very specific examples of how you’d want to use them.

APIs are important because it means developers don’t have to keep building the same software solutions over and over from scratch. APIs mean developers can take advantage of other platforms that have already been created and integrate their functionality into their own programs. Many big platforms have APIs, including Twitter and GitHub.

Types of API

For the Team
You might have an API that is internal to your company and therefore intended to be used only by members of your team. The purpose of this type of API would be to streamline the transfer of data between teams and systems, so your company’s internal developers are the ones who would be in charge of using this API.

For the Partners
Partner APIs are shared outside the organization but only with those who have a business relationship with the company who is providing the API. Only authorized clients have access to the API and as a consequence security measures tend to be more stringent with this type of API.

For the End-users
APIs for end-users or open APIs can be used by any developer without any restrictions. These types of APIs don’t have particularly strict authentication and authorization measures because the providers want the API to be adopted by as many developers as possible. Sometimes this type of API will be available for a subscription fee which is tiered depending on the number of API calls being made.

Who Writes API documentation?

Naturally, as developers are the ones who actually build the APIs they are often tasked with writing the documentation. Unfortunately, developer-driven documentation can often be overly technical because developers are so close to the subject matter. Documentation written by developers may also fall by the wayside as developers are actually focused on building and maintaining the API.

For this reason, many companies employ professional technical writers to create their API documentation. Technical writers have the technical ability to understand the API and the creative skills to be able to write engaging content for end users who are developers.

The API developers supply the technical writer with the information they need to be able to document the API accurately. If there are any parts missing from the documentation the developers can help the technical writer fill them in, with the end result that you have a document that is clear and accessible for its target audience.

Benefits of API Documentation

For providers who want to offer an API, developing documentation can have many important benefits for your organization.

Enhances the API’s Developer Experience
First and foremost, API documentation improves the developer experience. It doesn’t matter how good your API is if potential developers don’t understand how to use it. Good API documentation helps developers understand the different endpoints it has to offer and examples of particular use cases. When you improve the developer experience you increase the number of potential users you are able to attract to your product.

Reduces Time Spent Onboarding Internal Developers or External Partners Good API documentation means your support and success teams need to spend less time onboarding new internal developers or external partners. New users of your API have all the information they need to get started with your platform and set themselves up for success. When the processes are documented it removes the need for particular team members to intervene.

Efficient product upkeep and faster updates
When you document your API effectively it means you can manage the upkeep of your product and update it more quickly. With API documentation you know exactly what your product is meant to do and how it is supposed to help end users. Documentation gives you a more intimate view of the API and allows you to roll out faster updates that will be adopted by users.

Aids Both Internal and External Users in Comprehending the API and its Capabilities
One of the main benefits of API documentation is that it helps both internal and external users to understand the API, what it can be used for, and how you can deploy the API for your own ends. If you don’t explain the potential capabilities of the API then new users won’t know how to use it and you’ll experience slow product adoption. Potential users of an API use the documentation as a way to make the decision whether or not to use your product.

The Go-to Source for Team Members to Refer to API Goals
Internal team members in your organization can refer to the API documentation when they want to familiarize themselves with the goals of your API. Even those who weren’t directly involved in building the API or writing the documentation will understand the intended purpose of the API and be able to support the work of the API development team.

Allows to identify bugs quickly and issues
When you document the API this allows you to quickly identify bugs and issues as a result of testing the API to document all its features. If your API doesn’t work as designed this feedback can be passed on to the API development team who can then take steps to fix any problems. The result is a more professional and effective API that works as expected.

The Structure of API Documentation – Design and Function

An Outline
The outline of your API documentation is also known as the overview. It contains a summary of the API and its purpose, and may inform potential users about the benefits of using this API over others.

Continue reading the full article at Document360

How to use data and analytics in your documentation team

Aakhil Karthikkeyan — Tue, 27 Sep 2022 09:08:37 +0000

Introduction

Producing good-quality technical documentation is a skill that is mastered by talented technical content writers. The technical content writers shall know the customer’s needs before composing a technical article. Understanding customer needs is very tricky when you are composing new articles for yet-to-be-released product features for a public knowledge. However, for an internal knowledge base, it is easy to understand the customer needs as consultation can happen to gather internal customer requirements.

Understanding customer needs can be done through feedback received from the customer support team and customer success team as they manage customer relationships. Once there is clarity on customer needs, it becomes easy to produce technical documentation to meet them. However, the customer needs change over time. How do you keep up with your changing customer needs?

Why do we need data analytics?

Say “hello” to data-driven decision-making. We need to collect data to understand the customer intent and published article performance. The articles need to be monitored to improvising their quality over time such that articles are always living up to changing customer expectations. Data helps to perform analytics to derive key metrics for decision-making. The documentation team shall embrace the data-driven culture and have the mindset to use evidence to substantiate their opinions. The data provides a scientific approach to problem-solving and empowers the documentation team to make the right decision at the right time.

Data-powered documentation team also can derive business metrics to quantify the business value proposition of their efforts. This includes customer outcome metrics such as

Reduction in customer support tickets
Reduction in customer support phone calls
Increase in customer satisfaction
Increase in knowledge retention

What kind of data are needed?

The documentation team needs data that is fit for the purpose and helps them to make the right decision. These datasets can be grouped into themes such as

Product usage data
Customer support tickets
Google Analytics
Feature requests
Customer feedback

Product usage data

This dataset includes how customers are using the software product/ tool; This includes product feature usage data, customer usage behavioural data, customer recurring steps, and habitual data. This data is very rich in understanding the pain points customer are facing in configuring the product features. This data also unearths how customers are using the product features to solve their business problems. Understanding the product features and usage trends based on different customer personas can help technical content writers to form a good narrative and design the content structure accordingly.

Customer support tickets

The customer support tickets are raised as the customer wishes to resolve an issue relating to the software product. The qualitative data from the customer support team helps technical content writers to write appropriate troubleshooting guides. Understanding general themes in customer support tickets help technical writers to prioritize their effort and focus on recurring issues. The volume of customer ticket data over time shows the efficacy of technical writers’ effort to solve customer issues via self-service knowledge base.

Google Analytics

Google analytics provides a plethora of insights into how customers are navigating your knowledge base to find the information they seek for. It also provides rich analytics into customer demographics, behaviour, engagement, and traffic referrals. Technical writers need to understand how customers are consuming the content and help to optimize content. The other tools, such as hotjar provides powerful insights on how intuitive your content design is.

Feature requests

The number of product feature request raised by customers provides actionable insights into addressing untapped customer value. Technical writers may need to tweak the existing documentation article such that product features can be explained more intuitively from customer perspective. The technical writer’s team can exhibit empathy towards customer needs based on these feature requests.

Customer feedback

The customer feedbacks are very focused on improvising the documentation quality. These feedback datasets are authentic and help content writers to author content better. The likes/dislikes data, along with feedback, helps with the continual improvement of documentation quality.

What metrics are required for decision-making?

Since we have a plethora of data, what kind of metrics we need to build? The three principles for creating good metrics for data-driven decision making are

Intuitive
Interpretable
Actionable

Continue reading the full article at Document360

Creating a Technical Manual: How, Types & Examples

Aakhil Karthikkeyan — Wed, 21 Sep 2022 16:38:32 +0000

Unless your product is the most intuitive on the planet, it’s likely that you’ll need to rely on technical manuals to help your users. Without a technical manual, companies are heavily dependent on their customer support teams to assist their users, with support queues growing exponentially and chronically dissatisfied customers.

No product is complete without the technical manual. Not only is it useful for helping customers to troubleshoot problems, but it can also serve as a vital marketing asset that shows customers how much you invest in their successful onboarding.

Creating a technical manual is no easy feat, which is why in this article we’ll be going through the steps you need to take and a list of best practices.

What is a Technical Manual?

A technical manual can be thought of as a “how-to guide” aimed at helping users to understand the technical aspects of a product. Depending on the product, the technical manual usually contains instructions for the set-up, maintenance, and troubleshooting required for users to be effective.

The technical manual not only helps users get started but also assists them with ongoing problems they might face. It usually contains step-by-step instructions and how-to articles that helps users tackle any situation that might arise with the product.

A good technical manual should be simplified enough to make sense to the end users. It’s clear and well-structured,

Types of Technical Manual

There are many different types of technical manuals that companies might produce to help their users.

Product Manuals
Product manuals provide users with a basic overview of a product, without going into too much depth. It tells users what the product is for, explains its features, and how to set up, maintain and use the product.

Repair Manuals
Repair manuals are exactly what the name implies – detailed instructions for how to troubleshoot the product in the event an issue arises. It helps users conduct routine maintenance as well as performing major repairs.

Troubleshoot Guides
A troubleshooting guide is a structured document that lists common problems that might arise with a system, alongside instructions for how to solve the problem. It diagnoses symptoms, eliminates possible causes and confirms to the user when the system is operational again.

User Manuals
A user manual is an in-depth guide that helps customers get familiar with your product or service and overcome basic issues with the setup and maintenance. The user manual tells the user exactly how to use the product in its intended manner and helps them get the most out of it.

API Documentation
API documentation is a comprehensive reference manual that explains to users how to work with and integrate the software’s API. It contains details relating to the functions, classes, return types, and arguments, alongside tutorials and practical working examples.

Software Development Kit Documentation
An SDK is a set of tools, libraries, documentation, code samples, processes, and guides that enable software developers to build software applications on a particular platform.

Release Notes
Release notes are technical documentation that are provided alongside the release of a new software product or update. It usually contains details on how the product has changed, new or enhanced features, and bug fixes.

Why do Businesses Invest in Technical manuals?

There are many reasons why businesses choose to invest their resources into creating technical manuals.

Quick and easy onboarding of users
When you acquire a new user of your product, they are usually excited to get started. The problem is, most products require a little hand holding to get set up and guide your user towards success.

This is where technical manuals come in handy. New users can refer to your technical manual to help them install and launch your product, decreasing the time it takes for the user to become proficient with your product.

Guide user to operate in safe environment
Some products can present a potential danger to users if operated incorrectly. Technical manuals can provide the relevant warnings to make sure users interact with the product safely, such as the correct temperature for storage or keeping it away from liquids.

Improve customer experience with your product
When users understand how to use your product correctly, this enhances the customer experience. They have access to helpful resources that can provide instant answers to any questions they might have, without the necessity to contact customer support.

If customers can self-serve their own problems with your product, they feel less of a sense that they have been inconvenienced. Your company has already anticipated scenarios where users might need help, resulting in more successful and satisfied customers.

Effective training materials for operators and new users
Many products require an explanation before they can be used effectively, or instructions to help troubleshoot if the product doesn’t work as expected. Technical manuals are therefore useful training materials for operators and new users of the product, allowing them to get familiar with your product as they use it.

When customers are effectively trained with your product, they can become power users without having to reach out to customer support. This reduces the chance that they will churn.

Avoid liability due to product misuse
When you include correct usage instructions in your technical manual, you are protecting your company against liabilities that might arise through the use of your product. When you include the relevant warnings and disclaimers, you are able to present a valid defence against liability in the case that customers have ignored them.

Improve customer retention
Customers who enjoy using your product are more likely to keep using it in the long-term. Providing helpful technical documentation can help in the retention of customers by enabling them to overcome common problems by themselves. If customers experience a high level of frustration with your product, this makes them more likely to stop using it or to return it.

The technical manual is an investment in the company’s relationship with the customer. The company is taking responsibility for the customer’s success and ensuring that the product keeps working.

How to Write a Stunning Technical Manual

Now we’ll go through the exact steps you need to take to write a highly effective technical manual....

Continue reading the full article at Document360