#context.io

[topicprinter]

Article URL: https://imapapi.com/

Comments URL: https://news.ycombinator.com/item?id=22459212

Points: 6

# Comments: 0

[waltercostellone]

The Ten Essentials for Good API Documentation

API documentation is the number one reference for anyone implementing your API, and it can profoundly influence the developer experience. Because it describes what services an application programming interface offers and how to use those services, your documentation will inevitably create an impression about your product—for better or for worse.

In this two-part series I share what I’ve learned about API documentation. This part discusses the basics to help you create good API docs, while in part two, Ten Extras for Great API Documentation, I’ll show you additional ways to improve and fine-tune your documentation. 

Know your audience

Knowing who you address with your writing and how you can best support them will help you make decisions about the design, structure, and language of your docs. You will have to know who visits your API documentation and what they want to use it for. 

Your API documentation will probably be visited and used by the following audiences. 

Developers

Based on their skills, experience, and role in projects, developers will generally be the largest and most diverse group. They’ll be using your docs in different ways.

At Pronovix, we started conducting developer portal workshops with our clients to help them learn more about what developers need and how to best support their work—and what they’re really looking for in API documentation. This is also supported by solid research, such as the findings published in Stephanie Steinhardt’s article following a two-year research program at Merseburg University of Applied Sciences.

Newcomers: Developers lacking previous experience with your API tend to need the most support. They will take advantage of quickstart guides that encourage them to start using your API—clear, concise, step-by-step tutorials for the most important topics, and sample code and examples to help them understand how to use it in real projects. If you can make onboarding pleasant for newcomers, they will be more likely to devote themselves to learning every nuance of your API.

External developers: Developers already working with your API will come back repeatedly to your docs and use them as reference material. They will need quick information on all the functionality your API offers, structured in an easy to understand way to help them quickly find what they need.

Debuggers: Developers using your API will encounter errors from time to time and use your documentation to analyze the responses and errors that crop up.

Internal developers: API providers tend to focus so much on their external audience that they forget about their own developers; internal teams working on the API will use the API documentation, as well.

These are just the most common use cases.

Decision makers

Decision makers like CTOs and product managers will also check out your API documentation and evaluate your API. They need to determine whether your API will be a good fit for their project or not, so it’s crucial to your business that this group can easily and quickly find what they’re looking for.

Other audiences

Although not as common, journalists, technical writers, support staff, developer evangelists, and even your competition might read your API documentation. 

Remember the purpose of documentation

The foundation of your API documentation is a clear explanation of every call and parameter.

As a bare minimum, you should describe in detail:

what each call in your API does

each parameter and all of their possible values, including their types, formatting, rules, and whether or not they are required.

Context-based structure

People won’t read your API documentation in order, and you can’t predict which part they will land on. This means, you have to provide all the information they need in context. So following the best practices of topic-based authoring, you should include all necessary and related information in the explanation of each call.

Context.IO, for example, did a great job documenting each of their API calls separately with detailed information on parameters and their possible values, along with useful tips and links to related topics.

Examples

In order to be able to implement your API, developers need to understand it along with the domain it refers to (e.g., ecommerce). Real world examples reduce the time they need to get familiar with your product, and provide domain knowledge at the same time.

Add the following to the description of each call:

an example of how the call is made

an explanation of the request

sample responses

Studies have shown, that some developers immediately like to delve into coding, when getting to know a new API; they start working from an example. Analysis of eye-tracking records showed that visual elements, like example code, caught the attention of developers who were scanning the page, rather than reading it line by line.  Many looked at code samples before they started reading the descriptions.

Using the right examples is a surefire way to improving your API docs. I’ll explore ways to turn good API docs into great ones using examples in my upcoming post “Ten Extras for Great API Documentation”.

Error messages

When something goes wrong during development, fixing the problem without detailed documentation can become a frustrating and time-consuming process. To make this process as smooth as possible, error messages should help developers understand:

what the problem is;

whether the error stems from their code or from the use of the API;

and how to fix the problem.

All possible errors—including edge cases—should be documented with error-codes or brief, human-readable information in error messages. Error messages should not only contain information related to that specific call, but also address universal topics like authentication or HTTP requests and other conditions not controlled by the API (like request timeout or unknown server error).

This post from Box discusses best practices for server-side error handling and communication, such as returning an HTTP status code that closely matches the error condition, human-readable error messages, and machine-readable error codes.

Quickstart guide

Newcomers starting to implement your API face many obstacles:

They are at the beginning of a steep learning curve

They might not be familiar with the structure, domain, and ideas behind your API

It’s difficult for them to figure out where to start.

If you don’t make the learning process easier for them, they can feel overwhelmed and refrain from delving into your API. 

Many developers learn best by doing, so a quickstart guide is a great option. The guide should be short and simple, aimed at newcomers, and list the minimum number of steps required to complete a meaningful task (e.g., downloading the SDK and saving one object to the platform). Quickstart guides usually have to include information about the domain and introduce domain-related expressions and methods in more detail. It’s safest to assume that the developer has never before heard of your service.

Stripe’s and Braintree’s quickstart guides are great examples; both provide an overview of the most likely tasks you’ll want to perform with the API, as well as link you to the relevant information. They also contain links to contact someone if you need help.

Tutorials

Tutorials are step-by-step walkthroughs covering specific functionality developers can implement with your API, like SMS notifications, account verification, etc.

Tutorials for APIs should follow the best practices for writing any kind of step-by-step help. Each step should contain all the information needed at that point—and nothing more. This way users can focus on the task at hand and won’t be overloaded with information they don’t need.

The description of steps should be easy to follow and concise. Clarity and brevity support the learning process, and are a best practice for all kinds of documentation. Avoid jargon, if possible; users will be learning domain-related language and new technology, and jargon can instill confusion. Help them by making all descriptions as easy to understand as possible. 

The walkthrough should be the smallest possible chunk that lets the user finish a task. If a process is too complex, think about breaking it down into smaller chunks. This makes sure that users can get the help they need without going through steps they’re not interested in.

Twilio’s tutorials explain the most-likely use cases with sample apps in a wide variety of programming languages and frameworks. Universal topics

To implement your API, there are some larger topics that developers will need to know about, for example:

Authentication. Handled differently by each type of API, authentication (e.g., OAuth) is often a complicated and error-prone process. Explain how to get credentials, how they are passed on to the server, and show how API keys work with sample code.

Error handling. For now, error handling hasn’t been standardized, so you should help developers understand how your API passes back error information, why an error occurs, and how to fix it.

HTTP requests. You may have to document HTTP-related information as well, like content types, status codes, and caching.

Dedicate a separate section to explaining these topics, and link to this section from each related API call. This way you can make sure that developers clearly see how your API handles these topics and how API calls change behavior based on them. 

Layout and navigation

Layout and navigation are essential to user experience, and although there is no universal solution for all API docs, there are some best practices that help users interact with the material.

Dynamic layout

Most good examples of API documentation use a dynamic layout as it makes navigation easier for users than static layouts when looking for specific topics in extensive documentation. Starting with a scalable dynamic layout will also make sure you can easily expand your docs, as needed.

Single page design

If your API documentation isn’t huge, go with a single page design that lets users see the overall structure at first sight. Introduce the details from there. Long, single page docs also make it possible for readers to use the browser’s search functionality.

Stripe managed to present extensive documentation in an easy to navigate single page. Persistent navigation

Keep navigation visible at all times. Users don’t want to scroll looking for a navigation bar that disappeared.

Multi-column layout

2- or 3-column layouts have the navigation on the left and information and examples on the right. They make comprehension easier by showing endpoints and examples in context.

Clearbit’s three-column layout displays persistent navigation (table of contents) on the left, references in the middle, and code examples on the right. Syntax highlighter

Improving the readability of samples with syntax highlighting makes the code easier to understand.

The syntax highlighter in action on Plaid’s API documentation site.

If you’d like to start experimenting with a layout for your docs, you might want to check out some free and open source API documentation generators.

To learn about the pros and cons of different approaches to organizing your API docs in the context of developer portals, this is an excellent article by Nordic APIs.

Editing

All writing that you publish should go through an editing process. This is common sense for articles and other publications, but it’s just as essential for technical documentation.

The writers of your API docs should aim for clarity and brevity, confirm that all the necessary information is there, and that the structure is logical and topics aren’t diluted with unnecessary content. 

Editors should proofread your documentation to catch grammar mistakes, errors, and any parts that might be hard to read or difficult to understand. They should also check the docs against your style guide for technical documentation and suggest changes, if needed.

Once a section of documentation is ready to be published, it’s a good idea to show it to people in your target audience, especially any developers who haven’t worked on the documentation themselves. They can catch inconsistencies and provide insight into what’s missing.

Although the editing process can feel like a burden when you have to focus on so many other aspects of your API, a couple of iterations can make a huge difference in the final copy and the impression you make.

Keep it up-to-date

If your API documentation is out of date, users will get frustrated by bumping into features that aren’t there anymore and new ones that lack documentation. This can quickly diminish the trust you established by putting so much work into your documentation in the first place.

When maintaining your API docs, you should keep an eye on the following aspects:

Deprecated features. Remove documentation for deprecated features and explain why they were deprecated.

New features. Document new features before launch, and make sure there’s enough time planned for the new content to go through the editorial process.

Feedback. Useful feedback you get from support, or analytics should be reflected in your docs. Chances are you can’t make your docs perfect at the first try, but based on what users are saying, you can improve them continuously.

For all this to work, you will have to build a workflow for maintaining your documentation. Think about checkpoints and processes for the above mentioned aspects, editing, and publication. It also helps if you can set up a routine for reviewing your docs regularly (e.g. quarterly).

Following these best practices, you can build a solid foundation for your API documentation that can be continuously improved upon as you gain more insight into how users interact with them. Stay tuned for part two, where I give you some tips on how to turn good API docs into amazing ones.

http://ift.tt/2f83Bu0

[aracecvliwest]

The Ten Essentials for Good API Documentation

API documentation is the number one reference for anyone implementing your API, and it can profoundly influence the developer experience. Because it describes what services an application programming interface offers and how to use those services, your documentation will inevitably create an impression about your product—for better or for worse.

In this two-part series I share what I’ve learned about API documentation. This part discusses the basics to help you create good API docs, while in part two, Ten Extras for Great API Documentation, I’ll show you additional ways to improve and fine-tune your documentation. 

Know your audience

Knowing who you address with your writing and how you can best support them will help you make decisions about the design, structure, and language of your docs. You will have to know who visits your API documentation and what they want to use it for. 

Your API documentation will probably be visited and used by the following audiences. 

Developers

Based on their skills, experience, and role in projects, developers will generally be the largest and most diverse group. They’ll be using your docs in different ways.

At Pronovix, we started conducting developer portal workshops with our clients to help them learn more about what developers need and how to best support their work—and what they’re really looking for in API documentation. This is also supported by solid research, such as the findings published in Stephanie Steinhardt’s article following a two-year research program at Merseburg University of Applied Sciences.

Newcomers: Developers lacking previous experience with your API tend to need the most support. They will take advantage of quickstart guides that encourage them to start using your API—clear, concise, step-by-step tutorials for the most important topics, and sample code and examples to help them understand how to use it in real projects. If you can make onboarding pleasant for newcomers, they will be more likely to devote themselves to learning every nuance of your API.

External developers: Developers already working with your API will come back repeatedly to your docs and use them as reference material. They will need quick information on all the functionality your API offers, structured in an easy to understand way to help them quickly find what they need.

Debuggers: Developers using your API will encounter errors from time to time and use your documentation to analyze the responses and errors that crop up.

Internal developers: API providers tend to focus so much on their external audience that they forget about their own developers; internal teams working on the API will use the API documentation, as well.

These are just the most common use cases.

Decision makers

Decision makers like CTOs and product managers will also check out your API documentation and evaluate your API. They need to determine whether your API will be a good fit for their project or not, so it’s crucial to your business that this group can easily and quickly find what they’re looking for.

Other audiences

Although not as common, journalists, technical writers, support staff, developer evangelists, and even your competition might read your API documentation. 

Remember the purpose of documentation

The foundation of your API documentation is a clear explanation of every call and parameter.

As a bare minimum, you should describe in detail:

what each call in your API does

each parameter and all of their possible values, including their types, formatting, rules, and whether or not they are required.

Context-based structure

People won’t read your API documentation in order, and you can’t predict which part they will land on. This means, you have to provide all the information they need in context. So following the best practices of topic-based authoring, you should include all necessary and related information in the explanation of each call.

Context.IO, for example, did a great job documenting each of their API calls separately with detailed information on parameters and their possible values, along with useful tips and links to related topics.

Examples

In order to be able to implement your API, developers need to understand it along with the domain it refers to (e.g., ecommerce). Real world examples reduce the time they need to get familiar with your product, and provide domain knowledge at the same time.

Add the following to the description of each call:

an example of how the call is made

an explanation of the request

sample responses

Studies have shown, that some developers immediately like to delve into coding, when getting to know a new API; they start working from an example. Analysis of eye-tracking records showed that visual elements, like example code, caught the attention of developers who were scanning the page, rather than reading it line by line.  Many looked at code samples before they started reading the descriptions.

Using the right examples is a surefire way to improving your API docs. I’ll explore ways to turn good API docs into great ones using examples in my upcoming post “Ten Extras for Great API Documentation”.

Error messages

When something goes wrong during development, fixing the problem without detailed documentation can become a frustrating and time-consuming process. To make this process as smooth as possible, error messages should help developers understand:

what the problem is;

whether the error stems from their code or from the use of the API;

and how to fix the problem.

All possible errors—including edge cases—should be documented with error-codes or brief, human-readable information in error messages. Error messages should not only contain information related to that specific call, but also address universal topics like authentication or HTTP requests and other conditions not controlled by the API (like request timeout or unknown server error).

This post from Box discusses best practices for server-side error handling and communication, such as returning an HTTP status code that closely matches the error condition, human-readable error messages, and machine-readable error codes.

Quickstart guide

Newcomers starting to implement your API face many obstacles:

They are at the beginning of a steep learning curve

They might not be familiar with the structure, domain, and ideas behind your API

It’s difficult for them to figure out where to start.

If you don’t make the learning process easier for them, they can feel overwhelmed and refrain from delving into your API. 

Many developers learn best by doing, so a quickstart guide is a great option. The guide should be short and simple, aimed at newcomers, and list the minimum number of steps required to complete a meaningful task (e.g., downloading the SDK and saving one object to the platform). Quickstart guides usually have to include information about the domain and introduce domain-related expressions and methods in more detail. It’s safest to assume that the developer has never before heard of your service.

Stripe’s and Braintree’s quickstart guides are great examples; both provide an overview of the most likely tasks you’ll want to perform with the API, as well as link you to the relevant information. They also contain links to contact someone if you need help.

Tutorials

Tutorials are step-by-step walkthroughs covering specific functionality developers can implement with your API, like SMS notifications, account verification, etc.

Tutorials for APIs should follow the best practices for writing any kind of step-by-step help. Each step should contain all the information needed at that point—and nothing more. This way users can focus on the task at hand and won’t be overloaded with information they don’t need.

The description of steps should be easy to follow and concise. Clarity and brevity support the learning process, and are a best practice for all kinds of documentation. Avoid jargon, if possible; users will be learning domain-related language and new technology, and jargon can instill confusion. Help them by making all descriptions as easy to understand as possible. 

The walkthrough should be the smallest possible chunk that lets the user finish a task. If a process is too complex, think about breaking it down into smaller chunks. This makes sure that users can get the help they need without going through steps they’re not interested in.

Twilio’s tutorials explain the most-likely use cases with sample apps in a wide variety of programming languages and frameworks. Universal topics

To implement your API, there are some larger topics that developers will need to know about, for example:

Authentication. Handled differently by each type of API, authentication (e.g., OAuth) is often a complicated and error-prone process. Explain how to get credentials, how they are passed on to the server, and show how API keys work with sample code.

Error handling. For now, error handling hasn’t been standardized, so you should help developers understand how your API passes back error information, why an error occurs, and how to fix it.

HTTP requests. You may have to document HTTP-related information as well, like content types, status codes, and caching.

Dedicate a separate section to explaining these topics, and link to this section from each related API call. This way you can make sure that developers clearly see how your API handles these topics and how API calls change behavior based on them. 

Layout and navigation

Layout and navigation are essential to user experience, and although there is no universal solution for all API docs, there are some best practices that help users interact with the material.

Dynamic layout

Most good examples of API documentation use a dynamic layout as it makes navigation easier for users than static layouts when looking for specific topics in extensive documentation. Starting with a scalable dynamic layout will also make sure you can easily expand your docs, as needed.

Single page design

If your API documentation isn’t huge, go with a single page design that lets users see the overall structure at first sight. Introduce the details from there. Long, single page docs also make it possible for readers to use the browser’s search functionality.

Stripe managed to present extensive documentation in an easy to navigate single page. Persistent navigation

Keep navigation visible at all times. Users don’t want to scroll looking for a navigation bar that disappeared.

Multi-column layout

2- or 3-column layouts have the navigation on the left and information and examples on the right. They make comprehension easier by showing endpoints and examples in context.

Clearbit’s three-column layout displays persistent navigation (table of contents) on the left, references in the middle, and code examples on the right. Syntax highlighter

Improving the readability of samples with syntax highlighting makes the code easier to understand.

The syntax highlighter in action on Plaid’s API documentation site.

If you’d like to start experimenting with a layout for your docs, you might want to check out some free and open source API documentation generators.

To learn about the pros and cons of different approaches to organizing your API docs in the context of developer portals, this is an excellent article by Nordic APIs.

Editing

All writing that you publish should go through an editing process. This is common sense for articles and other publications, but it’s just as essential for technical documentation.

The writers of your API docs should aim for clarity and brevity, confirm that all the necessary information is there, and that the structure is logical and topics aren’t diluted with unnecessary content. 

Editors should proofread your documentation to catch grammar mistakes, errors, and any parts that might be hard to read or difficult to understand. They should also check the docs against your style guide for technical documentation and suggest changes, if needed.

Once a section of documentation is ready to be published, it’s a good idea to show it to people in your target audience, especially any developers who haven’t worked on the documentation themselves. They can catch inconsistencies and provide insight into what’s missing.

Although the editing process can feel like a burden when you have to focus on so many other aspects of your API, a couple of iterations can make a huge difference in the final copy and the impression you make.

Keep it up-to-date

If your API documentation is out of date, users will get frustrated by bumping into features that aren’t there anymore and new ones that lack documentation. This can quickly diminish the trust you established by putting so much work into your documentation in the first place.

When maintaining your API docs, you should keep an eye on the following aspects:

Deprecated features. Remove documentation for deprecated features and explain why they were deprecated.

New features. Document new features before launch, and make sure there’s enough time planned for the new content to go through the editorial process.

Feedback. Useful feedback you get from support, or analytics should be reflected in your docs. Chances are you can’t make your docs perfect at the first try, but based on what users are saying, you can improve them continuously.

For all this to work, you will have to build a workflow for maintaining your documentation. Think about checkpoints and processes for the above mentioned aspects, editing, and publication. It also helps if you can set up a routine for reviewing your docs regularly (e.g. quarterly).

Following these best practices, you can build a solid foundation for your API documentation that can be continuously improved upon as you gain more insight into how users interact with them. Stay tuned for part two, where I give you some tips on how to turn good API docs into amazing ones.

http://ift.tt/2f83Bu0

[jeanshesallenberger]

The Ten Essentials for Good API Documentation

API documentation is the number one reference for anyone implementing your API, and it can profoundly influence the developer experience. Because it describes what services an application programming interface offers and how to use those services, your documentation will inevitably create an impression about your product—for better or for worse.

In this two-part series I share what I’ve learned about API documentation. This part discusses the basics to help you create good API docs, while in part two, Ten Extras for Great API Documentation, I’ll show you additional ways to improve and fine-tune your documentation. 

Know your audience

Knowing who you address with your writing and how you can best support them will help you make decisions about the design, structure, and language of your docs. You will have to know who visits your API documentation and what they want to use it for. 

Your API documentation will probably be visited and used by the following audiences. 

Developers

Based on their skills, experience, and role in projects, developers will generally be the largest and most diverse group. They’ll be using your docs in different ways.

At Pronovix, we started conducting developer portal workshops with our clients to help them learn more about what developers need and how to best support their work—and what they’re really looking for in API documentation. This is also supported by solid research, such as the findings published in Stephanie Steinhardt’s article following a two-year research program at Merseburg University of Applied Sciences.

Newcomers: Developers lacking previous experience with your API tend to need the most support. They will take advantage of quickstart guides that encourage them to start using your API—clear, concise, step-by-step tutorials for the most important topics, and sample code and examples to help them understand how to use it in real projects. If you can make onboarding pleasant for newcomers, they will be more likely to devote themselves to learning every nuance of your API.

External developers: Developers already working with your API will come back repeatedly to your docs and use them as reference material. They will need quick information on all the functionality your API offers, structured in an easy to understand way to help them quickly find what they need.

Debuggers: Developers using your API will encounter errors from time to time and use your documentation to analyze the responses and errors that crop up.

Internal developers: API providers tend to focus so much on their external audience that they forget about their own developers; internal teams working on the API will use the API documentation, as well.

These are just the most common use cases.

Decision makers

Decision makers like CTOs and product managers will also check out your API documentation and evaluate your API. They need to determine whether your API will be a good fit for their project or not, so it’s crucial to your business that this group can easily and quickly find what they’re looking for.

Other audiences

Although not as common, journalists, technical writers, support staff, developer evangelists, and even your competition might read your API documentation. 

Remember the purpose of documentation

The foundation of your API documentation is a clear explanation of every call and parameter.

As a bare minimum, you should describe in detail:

what each call in your API does

each parameter and all of their possible values, including their types, formatting, rules, and whether or not they are required.

Context-based structure

People won’t read your API documentation in order, and you can’t predict which part they will land on. This means, you have to provide all the information they need in context. So following the best practices of topic-based authoring, you should include all necessary and related information in the explanation of each call.

Context.IO, for example, did a great job documenting each of their API calls separately with detailed information on parameters and their possible values, along with useful tips and links to related topics.

Examples

In order to be able to implement your API, developers need to understand it along with the domain it refers to (e.g., ecommerce). Real world examples reduce the time they need to get familiar with your product, and provide domain knowledge at the same time.

Add the following to the description of each call:

an example of how the call is made

an explanation of the request

sample responses

Studies have shown, that some developers immediately like to delve into coding, when getting to know a new API; they start working from an example. Analysis of eye-tracking records showed that visual elements, like example code, caught the attention of developers who were scanning the page, rather than reading it line by line.  Many looked at code samples before they started reading the descriptions.

Using the right examples is a surefire way to improving your API docs. I’ll explore ways to turn good API docs into great ones using examples in my upcoming post “Ten Extras for Great API Documentation”.

Error messages

When something goes wrong during development, fixing the problem without detailed documentation can become a frustrating and time-consuming process. To make this process as smooth as possible, error messages should help developers understand:

what the problem is;

whether the error stems from their code or from the use of the API;

and how to fix the problem.

All possible errors—including edge cases—should be documented with error-codes or brief, human-readable information in error messages. Error messages should not only contain information related to that specific call, but also address universal topics like authentication or HTTP requests and other conditions not controlled by the API (like request timeout or unknown server error).

This post from Box discusses best practices for server-side error handling and communication, such as returning an HTTP status code that closely matches the error condition, human-readable error messages, and machine-readable error codes.

Quickstart guide

Newcomers starting to implement your API face many obstacles:

They are at the beginning of a steep learning curve

They might not be familiar with the structure, domain, and ideas behind your API

It’s difficult for them to figure out where to start.

If you don’t make the learning process easier for them, they can feel overwhelmed and refrain from delving into your API. 

Many developers learn best by doing, so a quickstart guide is a great option. The guide should be short and simple, aimed at newcomers, and list the minimum number of steps required to complete a meaningful task (e.g., downloading the SDK and saving one object to the platform). Quickstart guides usually have to include information about the domain and introduce domain-related expressions and methods in more detail. It’s safest to assume that the developer has never before heard of your service.

Stripe’s and Braintree’s quickstart guides are great examples; both provide an overview of the most likely tasks you’ll want to perform with the API, as well as link you to the relevant information. They also contain links to contact someone if you need help.

Tutorials

Tutorials are step-by-step walkthroughs covering specific functionality developers can implement with your API, like SMS notifications, account verification, etc.

Tutorials for APIs should follow the best practices for writing any kind of step-by-step help. Each step should contain all the information needed at that point—and nothing more. This way users can focus on the task at hand and won’t be overloaded with information they don’t need.

The description of steps should be easy to follow and concise. Clarity and brevity support the learning process, and are a best practice for all kinds of documentation. Avoid jargon, if possible; users will be learning domain-related language and new technology, and jargon can instill confusion. Help them by making all descriptions as easy to understand as possible. 

The walkthrough should be the smallest possible chunk that lets the user finish a task. If a process is too complex, think about breaking it down into smaller chunks. This makes sure that users can get the help they need without going through steps they’re not interested in.

Twilio’s tutorials explain the most-likely use cases with sample apps in a wide variety of programming languages and frameworks. Universal topics

To implement your API, there are some larger topics that developers will need to know about, for example:

Authentication. Handled differently by each type of API, authentication (e.g., OAuth) is often a complicated and error-prone process. Explain how to get credentials, how they are passed on to the server, and show how API keys work with sample code.

Error handling. For now, error handling hasn’t been standardized, so you should help developers understand how your API passes back error information, why an error occurs, and how to fix it.

HTTP requests. You may have to document HTTP-related information as well, like content types, status codes, and caching.

Dedicate a separate section to explaining these topics, and link to this section from each related API call. This way you can make sure that developers clearly see how your API handles these topics and how API calls change behavior based on them. 

Layout and navigation

Layout and navigation are essential to user experience, and although there is no universal solution for all API docs, there are some best practices that help users interact with the material.

Dynamic layout

Most good examples of API documentation use a dynamic layout as it makes navigation easier for users than static layouts when looking for specific topics in extensive documentation. Starting with a scalable dynamic layout will also make sure you can easily expand your docs, as needed.

Single page design

If your API documentation isn’t huge, go with a single page design that lets users see the overall structure at first sight. Introduce the details from there. Long, single page docs also make it possible for readers to use the browser’s search functionality.

Stripe managed to present extensive documentation in an easy to navigate single page. Persistent navigation

Keep navigation visible at all times. Users don’t want to scroll looking for a navigation bar that disappeared.

Multi-column layout

2- or 3-column layouts have the navigation on the left and information and examples on the right. They make comprehension easier by showing endpoints and examples in context.

Clearbit’s three-column layout displays persistent navigation (table of contents) on the left, references in the middle, and code examples on the right. Syntax highlighter

Improving the readability of samples with syntax highlighting makes the code easier to understand.

The syntax highlighter in action on Plaid’s API documentation site.

If you’d like to start experimenting with a layout for your docs, you might want to check out some free and open source API documentation generators.

To learn about the pros and cons of different approaches to organizing your API docs in the context of developer portals, this is an excellent article by Nordic APIs.

Editing

All writing that you publish should go through an editing process. This is common sense for articles and other publications, but it’s just as essential for technical documentation.

The writers of your API docs should aim for clarity and brevity, confirm that all the necessary information is there, and that the structure is logical and topics aren’t diluted with unnecessary content. 

Editors should proofread your documentation to catch grammar mistakes, errors, and any parts that might be hard to read or difficult to understand. They should also check the docs against your style guide for technical documentation and suggest changes, if needed.

Once a section of documentation is ready to be published, it’s a good idea to show it to people in your target audience, especially any developers who haven’t worked on the documentation themselves. They can catch inconsistencies and provide insight into what’s missing.

Although the editing process can feel like a burden when you have to focus on so many other aspects of your API, a couple of iterations can make a huge difference in the final copy and the impression you make.

Keep it up-to-date

If your API documentation is out of date, users will get frustrated by bumping into features that aren’t there anymore and new ones that lack documentation. This can quickly diminish the trust you established by putting so much work into your documentation in the first place.

When maintaining your API docs, you should keep an eye on the following aspects:

Deprecated features. Remove documentation for deprecated features and explain why they were deprecated.

New features. Document new features before launch, and make sure there’s enough time planned for the new content to go through the editorial process.

Feedback. Useful feedback you get from support, or analytics should be reflected in your docs. Chances are you can’t make your docs perfect at the first try, but based on what users are saying, you can improve them continuously.

For all this to work, you will have to build a workflow for maintaining your documentation. Think about checkpoints and processes for the above mentioned aspects, editing, and publication. It also helps if you can set up a routine for reviewing your docs regularly (e.g. quarterly).

Following these best practices, you can build a solid foundation for your API documentation that can be continuously improved upon as you gain more insight into how users interact with them. Stay tuned for part two, where I give you some tips on how to turn good API docs into amazing ones.

http://ift.tt/2f83Bu0

[joannlyfgnch]

The Ten Essentials for Good API Documentation

API documentation is the number one reference for anyone implementing your API, and it can profoundly influence the developer experience. Because it describes what services an application programming interface offers and how to use those services, your documentation will inevitably create an impression about your product—for better or for worse.

In this two-part series I share what I’ve learned about API documentation. This part discusses the basics to help you create good API docs, while in part two, Ten Extras for Great API Documentation, I’ll show you additional ways to improve and fine-tune your documentation. 

Know your audience

Knowing who you address with your writing and how you can best support them will help you make decisions about the design, structure, and language of your docs. You will have to know who visits your API documentation and what they want to use it for. 

Your API documentation will probably be visited and used by the following audiences. 

Developers

Based on their skills, experience, and role in projects, developers will generally be the largest and most diverse group. They’ll be using your docs in different ways.

At Pronovix, we started conducting developer portal workshops with our clients to help them learn more about what developers need and how to best support their work—and what they’re really looking for in API documentation. This is also supported by solid research, such as the findings published in Stephanie Steinhardt’s article following a two-year research program at Merseburg University of Applied Sciences.

Newcomers: Developers lacking previous experience with your API tend to need the most support. They will take advantage of quickstart guides that encourage them to start using your API—clear, concise, step-by-step tutorials for the most important topics, and sample code and examples to help them understand how to use it in real projects. If you can make onboarding pleasant for newcomers, they will be more likely to devote themselves to learning every nuance of your API.

External developers: Developers already working with your API will come back repeatedly to your docs and use them as reference material. They will need quick information on all the functionality your API offers, structured in an easy to understand way to help them quickly find what they need.

Debuggers: Developers using your API will encounter errors from time to time and use your documentation to analyze the responses and errors that crop up.

Internal developers: API providers tend to focus so much on their external audience that they forget about their own developers; internal teams working on the API will use the API documentation, as well.

These are just the most common use cases.

Decision makers

Decision makers like CTOs and product managers will also check out your API documentation and evaluate your API. They need to determine whether your API will be a good fit for their project or not, so it’s crucial to your business that this group can easily and quickly find what they’re looking for.

Other audiences

Although not as common, journalists, technical writers, support staff, developer evangelists, and even your competition might read your API documentation. 

Remember the purpose of documentation

The foundation of your API documentation is a clear explanation of every call and parameter.

As a bare minimum, you should describe in detail:

what each call in your API does

each parameter and all of their possible values, including their types, formatting, rules, and whether or not they are required.

Context-based structure

People won’t read your API documentation in order, and you can’t predict which part they will land on. This means, you have to provide all the information they need in context. So following the best practices of topic-based authoring, you should include all necessary and related information in the explanation of each call.

Context.IO, for example, did a great job documenting each of their API calls separately with detailed information on parameters and their possible values, along with useful tips and links to related topics.

Examples

In order to be able to implement your API, developers need to understand it along with the domain it refers to (e.g., ecommerce). Real world examples reduce the time they need to get familiar with your product, and provide domain knowledge at the same time.

Add the following to the description of each call:

an example of how the call is made

an explanation of the request

sample responses

Studies have shown, that some developers immediately like to delve into coding, when getting to know a new API; they start working from an example. Analysis of eye-tracking records showed that visual elements, like example code, caught the attention of developers who were scanning the page, rather than reading it line by line.  Many looked at code samples before they started reading the descriptions.

Using the right examples is a surefire way to improving your API docs. I’ll explore ways to turn good API docs into great ones using examples in my upcoming post “Ten Extras for Great API Documentation”.

Error messages

When something goes wrong during development, fixing the problem without detailed documentation can become a frustrating and time-consuming process. To make this process as smooth as possible, error messages should help developers understand:

what the problem is;

whether the error stems from their code or from the use of the API;

and how to fix the problem.

All possible errors—including edge cases—should be documented with error-codes or brief, human-readable information in error messages. Error messages should not only contain information related to that specific call, but also address universal topics like authentication or HTTP requests and other conditions not controlled by the API (like request timeout or unknown server error).

This post from Box discusses best practices for server-side error handling and communication, such as returning an HTTP status code that closely matches the error condition, human-readable error messages, and machine-readable error codes.

Quickstart guide

Newcomers starting to implement your API face many obstacles:

They are at the beginning of a steep learning curve

They might not be familiar with the structure, domain, and ideas behind your API

It’s difficult for them to figure out where to start.

If you don’t make the learning process easier for them, they can feel overwhelmed and refrain from delving into your API. 

Many developers learn best by doing, so a quickstart guide is a great option. The guide should be short and simple, aimed at newcomers, and list the minimum number of steps required to complete a meaningful task (e.g., downloading the SDK and saving one object to the platform). Quickstart guides usually have to include information about the domain and introduce domain-related expressions and methods in more detail. It’s safest to assume that the developer has never before heard of your service.

Stripe’s and Braintree’s quickstart guides are great examples; both provide an overview of the most likely tasks you’ll want to perform with the API, as well as link you to the relevant information. They also contain links to contact someone if you need help.

Tutorials

Tutorials are step-by-step walkthroughs covering specific functionality developers can implement with your API, like SMS notifications, account verification, etc.

Tutorials for APIs should follow the best practices for writing any kind of step-by-step help. Each step should contain all the information needed at that point—and nothing more. This way users can focus on the task at hand and won’t be overloaded with information they don’t need.

The description of steps should be easy to follow and concise. Clarity and brevity support the learning process, and are a best practice for all kinds of documentation. Avoid jargon, if possible; users will be learning domain-related language and new technology, and jargon can instill confusion. Help them by making all descriptions as easy to understand as possible. 

The walkthrough should be the smallest possible chunk that lets the user finish a task. If a process is too complex, think about breaking it down into smaller chunks. This makes sure that users can get the help they need without going through steps they’re not interested in.

Twilio’s tutorials explain the most-likely use cases with sample apps in a wide variety of programming languages and frameworks. Universal topics

To implement your API, there are some larger topics that developers will need to know about, for example:

Authentication. Handled differently by each type of API, authentication (e.g., OAuth) is often a complicated and error-prone process. Explain how to get credentials, how they are passed on to the server, and show how API keys work with sample code.

Error handling. For now, error handling hasn’t been standardized, so you should help developers understand how your API passes back error information, why an error occurs, and how to fix it.

HTTP requests. You may have to document HTTP-related information as well, like content types, status codes, and caching.

Dedicate a separate section to explaining these topics, and link to this section from each related API call. This way you can make sure that developers clearly see how your API handles these topics and how API calls change behavior based on them. 

Layout and navigation

Layout and navigation are essential to user experience, and although there is no universal solution for all API docs, there are some best practices that help users interact with the material.

Dynamic layout

Most good examples of API documentation use a dynamic layout as it makes navigation easier for users than static layouts when looking for specific topics in extensive documentation. Starting with a scalable dynamic layout will also make sure you can easily expand your docs, as needed.

Single page design

If your API documentation isn’t huge, go with a single page design that lets users see the overall structure at first sight. Introduce the details from there. Long, single page docs also make it possible for readers to use the browser’s search functionality.

Stripe managed to present extensive documentation in an easy to navigate single page. Persistent navigation

Keep navigation visible at all times. Users don’t want to scroll looking for a navigation bar that disappeared.

Multi-column layout

2- or 3-column layouts have the navigation on the left and information and examples on the right. They make comprehension easier by showing endpoints and examples in context.

Clearbit’s three-column layout displays persistent navigation (table of contents) on the left, references in the middle, and code examples on the right. Syntax highlighter

Improving the readability of samples with syntax highlighting makes the code easier to understand.

The syntax highlighter in action on Plaid’s API documentation site.

If you’d like to start experimenting with a layout for your docs, you might want to check out some free and open source API documentation generators.

To learn about the pros and cons of different approaches to organizing your API docs in the context of developer portals, this is an excellent article by Nordic APIs.

Editing

All writing that you publish should go through an editing process. This is common sense for articles and other publications, but it’s just as essential for technical documentation.

The writers of your API docs should aim for clarity and brevity, confirm that all the necessary information is there, and that the structure is logical and topics aren’t diluted with unnecessary content. 

Editors should proofread your documentation to catch grammar mistakes, errors, and any parts that might be hard to read or difficult to understand. They should also check the docs against your style guide for technical documentation and suggest changes, if needed.

Once a section of documentation is ready to be published, it’s a good idea to show it to people in your target audience, especially any developers who haven’t worked on the documentation themselves. They can catch inconsistencies and provide insight into what’s missing.

Although the editing process can feel like a burden when you have to focus on so many other aspects of your API, a couple of iterations can make a huge difference in the final copy and the impression you make.

Keep it up-to-date

If your API documentation is out of date, users will get frustrated by bumping into features that aren’t there anymore and new ones that lack documentation. This can quickly diminish the trust you established by putting so much work into your documentation in the first place.

When maintaining your API docs, you should keep an eye on the following aspects:

Deprecated features. Remove documentation for deprecated features and explain why they were deprecated.

New features. Document new features before launch, and make sure there’s enough time planned for the new content to go through the editorial process.

Feedback. Useful feedback you get from support, or analytics should be reflected in your docs. Chances are you can’t make your docs perfect at the first try, but based on what users are saying, you can improve them continuously.

For all this to work, you will have to build a workflow for maintaining your documentation. Think about checkpoints and processes for the above mentioned aspects, editing, and publication. It also helps if you can set up a routine for reviewing your docs regularly (e.g. quarterly).

Following these best practices, you can build a solid foundation for your API documentation that can be continuously improved upon as you gain more insight into how users interact with them. Stay tuned for part two, where I give you some tips on how to turn good API docs into amazing ones.

http://ift.tt/2f83Bu0

[pattersondonaldblk5]

The Ten Essentials for Good API Documentation

API documentation is the number one reference for anyone implementing your API, and it can profoundly influence the developer experience. Because it describes what services an application programming interface offers and how to use those services, your documentation will inevitably create an impression about your product—for better or for worse.

In this two-part series I share what I’ve learned about API documentation. This part discusses the basics to help you create good API docs, while in part two, Ten Extras for Great API Documentation, I’ll show you additional ways to improve and fine-tune your documentation. 

Know your audience

Knowing who you address with your writing and how you can best support them will help you make decisions about the design, structure, and language of your docs. You will have to know who visits your API documentation and what they want to use it for. 

Your API documentation will probably be visited and used by the following audiences. 

Developers

Based on their skills, experience, and role in projects, developers will generally be the largest and most diverse group. They’ll be using your docs in different ways.

At Pronovix, we started conducting developer portal workshops with our clients to help them learn more about what developers need and how to best support their work—and what they’re really looking for in API documentation. This is also supported by solid research, such as the findings published in Stephanie Steinhardt’s article following a two-year research program at Merseburg University of Applied Sciences.

Newcomers: Developers lacking previous experience with your API tend to need the most support. They will take advantage of quickstart guides that encourage them to start using your API—clear, concise, step-by-step tutorials for the most important topics, and sample code and examples to help them understand how to use it in real projects. If you can make onboarding pleasant for newcomers, they will be more likely to devote themselves to learning every nuance of your API.

External developers: Developers already working with your API will come back repeatedly to your docs and use them as reference material. They will need quick information on all the functionality your API offers, structured in an easy to understand way to help them quickly find what they need.

Debuggers: Developers using your API will encounter errors from time to time and use your documentation to analyze the responses and errors that crop up.

Internal developers: API providers tend to focus so much on their external audience that they forget about their own developers; internal teams working on the API will use the API documentation, as well.

These are just the most common use cases.

Decision makers

Decision makers like CTOs and product managers will also check out your API documentation and evaluate your API. They need to determine whether your API will be a good fit for their project or not, so it’s crucial to your business that this group can easily and quickly find what they’re looking for.

Other audiences

Although not as common, journalists, technical writers, support staff, developer evangelists, and even your competition might read your API documentation. 

Remember the purpose of documentation

The foundation of your API documentation is a clear explanation of every call and parameter.

As a bare minimum, you should describe in detail:

what each call in your API does

each parameter and all of their possible values, including their types, formatting, rules, and whether or not they are required.

Context-based structure

People won’t read your API documentation in order, and you can’t predict which part they will land on. This means, you have to provide all the information they need in context. So following the best practices of topic-based authoring, you should include all necessary and related information in the explanation of each call.

Context.IO, for example, did a great job documenting each of their API calls separately with detailed information on parameters and their possible values, along with useful tips and links to related topics.

Examples

In order to be able to implement your API, developers need to understand it along with the domain it refers to (e.g., ecommerce). Real world examples reduce the time they need to get familiar with your product, and provide domain knowledge at the same time.

Add the following to the description of each call:

an example of how the call is made

an explanation of the request

sample responses

Studies have shown, that some developers immediately like to delve into coding, when getting to know a new API; they start working from an example. Analysis of eye-tracking records showed that visual elements, like example code, caught the attention of developers who were scanning the page, rather than reading it line by line.  Many looked at code samples before they started reading the descriptions.

Using the right examples is a surefire way to improving your API docs. I’ll explore ways to turn good API docs into great ones using examples in my upcoming post “Ten Extras for Great API Documentation”.

Error messages

When something goes wrong during development, fixing the problem without detailed documentation can become a frustrating and time-consuming process. To make this process as smooth as possible, error messages should help developers understand:

what the problem is;

whether the error stems from their code or from the use of the API;

and how to fix the problem.

All possible errors—including edge cases—should be documented with error-codes or brief, human-readable information in error messages. Error messages should not only contain information related to that specific call, but also address universal topics like authentication or HTTP requests and other conditions not controlled by the API (like request timeout or unknown server error).

This post from Box discusses best practices for server-side error handling and communication, such as returning an HTTP status code that closely matches the error condition, human-readable error messages, and machine-readable error codes.

Quickstart guide

Newcomers starting to implement your API face many obstacles:

They are at the beginning of a steep learning curve

They might not be familiar with the structure, domain, and ideas behind your API

It’s difficult for them to figure out where to start.

If you don’t make the learning process easier for them, they can feel overwhelmed and refrain from delving into your API. 

Many developers learn best by doing, so a quickstart guide is a great option. The guide should be short and simple, aimed at newcomers, and list the minimum number of steps required to complete a meaningful task (e.g., downloading the SDK and saving one object to the platform). Quickstart guides usually have to include information about the domain and introduce domain-related expressions and methods in more detail. It’s safest to assume that the developer has never before heard of your service.

Stripe’s and Braintree’s quickstart guides are great examples; both provide an overview of the most likely tasks you’ll want to perform with the API, as well as link you to the relevant information. They also contain links to contact someone if you need help.

Tutorials

Tutorials are step-by-step walkthroughs covering specific functionality developers can implement with your API, like SMS notifications, account verification, etc.

Tutorials for APIs should follow the best practices for writing any kind of step-by-step help. Each step should contain all the information needed at that point—and nothing more. This way users can focus on the task at hand and won’t be overloaded with information they don’t need.

The description of steps should be easy to follow and concise. Clarity and brevity support the learning process, and are a best practice for all kinds of documentation. Avoid jargon, if possible; users will be learning domain-related language and new technology, and jargon can instill confusion. Help them by making all descriptions as easy to understand as possible. 

The walkthrough should be the smallest possible chunk that lets the user finish a task. If a process is too complex, think about breaking it down into smaller chunks. This makes sure that users can get the help they need without going through steps they’re not interested in.

Twilio’s tutorials explain the most-likely use cases with sample apps in a wide variety of programming languages and frameworks. Universal topics

To implement your API, there are some larger topics that developers will need to know about, for example:

Authentication. Handled differently by each type of API, authentication (e.g., OAuth) is often a complicated and error-prone process. Explain how to get credentials, how they are passed on to the server, and show how API keys work with sample code.

Error handling. For now, error handling hasn’t been standardized, so you should help developers understand how your API passes back error information, why an error occurs, and how to fix it.

HTTP requests. You may have to document HTTP-related information as well, like content types, status codes, and caching.

Dedicate a separate section to explaining these topics, and link to this section from each related API call. This way you can make sure that developers clearly see how your API handles these topics and how API calls change behavior based on them. 

Layout and navigation

Layout and navigation are essential to user experience, and although there is no universal solution for all API docs, there are some best practices that help users interact with the material.

Dynamic layout

Most good examples of API documentation use a dynamic layout as it makes navigation easier for users than static layouts when looking for specific topics in extensive documentation. Starting with a scalable dynamic layout will also make sure you can easily expand your docs, as needed.

Single page design

If your API documentation isn’t huge, go with a single page design that lets users see the overall structure at first sight. Introduce the details from there. Long, single page docs also make it possible for readers to use the browser’s search functionality.

Stripe managed to present extensive documentation in an easy to navigate single page. Persistent navigation

Keep navigation visible at all times. Users don’t want to scroll looking for a navigation bar that disappeared.

Multi-column layout

2- or 3-column layouts have the navigation on the left and information and examples on the right. They make comprehension easier by showing endpoints and examples in context.

Clearbit’s three-column layout displays persistent navigation (table of contents) on the left, references in the middle, and code examples on the right. Syntax highlighter

Improving the readability of samples with syntax highlighting makes the code easier to understand.

The syntax highlighter in action on Plaid’s API documentation site.

If you’d like to start experimenting with a layout for your docs, you might want to check out some free and open source API documentation generators.

To learn about the pros and cons of different approaches to organizing your API docs in the context of developer portals, this is an excellent article by Nordic APIs.

Editing

All writing that you publish should go through an editing process. This is common sense for articles and other publications, but it’s just as essential for technical documentation.

The writers of your API docs should aim for clarity and brevity, confirm that all the necessary information is there, and that the structure is logical and topics aren’t diluted with unnecessary content. 

Editors should proofread your documentation to catch grammar mistakes, errors, and any parts that might be hard to read or difficult to understand. They should also check the docs against your style guide for technical documentation and suggest changes, if needed.

Once a section of documentation is ready to be published, it’s a good idea to show it to people in your target audience, especially any developers who haven’t worked on the documentation themselves. They can catch inconsistencies and provide insight into what’s missing.

Although the editing process can feel like a burden when you have to focus on so many other aspects of your API, a couple of iterations can make a huge difference in the final copy and the impression you make.

Keep it up-to-date

If your API documentation is out of date, users will get frustrated by bumping into features that aren’t there anymore and new ones that lack documentation. This can quickly diminish the trust you established by putting so much work into your documentation in the first place.

When maintaining your API docs, you should keep an eye on the following aspects:

Deprecated features. Remove documentation for deprecated features and explain why they were deprecated.

New features. Document new features before launch, and make sure there’s enough time planned for the new content to go through the editorial process.

Feedback. Useful feedback you get from support, or analytics should be reflected in your docs. Chances are you can’t make your docs perfect at the first try, but based on what users are saying, you can improve them continuously.

For all this to work, you will have to build a workflow for maintaining your documentation. Think about checkpoints and processes for the above mentioned aspects, editing, and publication. It also helps if you can set up a routine for reviewing your docs regularly (e.g. quarterly).

Following these best practices, you can build a solid foundation for your API documentation that can be continuously improved upon as you gain more insight into how users interact with them. Stay tuned for part two, where I give you some tips on how to turn good API docs into amazing ones.

http://ift.tt/2f83Bu0

[mariaaklnthony]

The Ten Essentials for Good API Documentation

API documentation is the number one reference for anyone implementing your API, and it can profoundly influence the developer experience. Because it describes what services an application programming interface offers and how to use those services, your documentation will inevitably create an impression about your product—for better or for worse.

In this two-part series I share what I’ve learned about API documentation. This part discusses the basics to help you create good API docs, while in part two, Ten Extras for Great API Documentation, I’ll show you additional ways to improve and fine-tune your documentation. 

Know your audience

Knowing who you address with your writing and how you can best support them will help you make decisions about the design, structure, and language of your docs. You will have to know who visits your API documentation and what they want to use it for. 

Your API documentation will probably be visited and used by the following audiences. 

Developers

Based on their skills, experience, and role in projects, developers will generally be the largest and most diverse group. They’ll be using your docs in different ways.

At Pronovix, we started conducting developer portal workshops with our clients to help them learn more about what developers need and how to best support their work—and what they’re really looking for in API documentation. This is also supported by solid research, such as the findings published in Stephanie Steinhardt’s article following a two-year research program at Merseburg University of Applied Sciences.

Newcomers: Developers lacking previous experience with your API tend to need the most support. They will take advantage of quickstart guides that encourage them to start using your API—clear, concise, step-by-step tutorials for the most important topics, and sample code and examples to help them understand how to use it in real projects. If you can make onboarding pleasant for newcomers, they will be more likely to devote themselves to learning every nuance of your API.

External developers: Developers already working with your API will come back repeatedly to your docs and use them as reference material. They will need quick information on all the functionality your API offers, structured in an easy to understand way to help them quickly find what they need.

Debuggers: Developers using your API will encounter errors from time to time and use your documentation to analyze the responses and errors that crop up.

Internal developers: API providers tend to focus so much on their external audience that they forget about their own developers; internal teams working on the API will use the API documentation, as well.

These are just the most common use cases.

Decision makers

Decision makers like CTOs and product managers will also check out your API documentation and evaluate your API. They need to determine whether your API will be a good fit for their project or not, so it’s crucial to your business that this group can easily and quickly find what they’re looking for.

Other audiences

Although not as common, journalists, technical writers, support staff, developer evangelists, and even your competition might read your API documentation. 

Remember the purpose of documentation

The foundation of your API documentation is a clear explanation of every call and parameter.

As a bare minimum, you should describe in detail:

what each call in your API does

each parameter and all of their possible values, including their types, formatting, rules, and whether or not they are required.

Context-based structure

People won’t read your API documentation in order, and you can’t predict which part they will land on. This means, you have to provide all the information they need in context. So following the best practices of topic-based authoring, you should include all necessary and related information in the explanation of each call.

Context.IO, for example, did a great job documenting each of their API calls separately with detailed information on parameters and their possible values, along with useful tips and links to related topics.

Examples

In order to be able to implement your API, developers need to understand it along with the domain it refers to (e.g., ecommerce). Real world examples reduce the time they need to get familiar with your product, and provide domain knowledge at the same time.

Add the following to the description of each call:

an example of how the call is made

an explanation of the request

sample responses

Studies have shown, that some developers immediately like to delve into coding, when getting to know a new API; they start working from an example. Analysis of eye-tracking records showed that visual elements, like example code, caught the attention of developers who were scanning the page, rather than reading it line by line.  Many looked at code samples before they started reading the descriptions.

Using the right examples is a surefire way to improving your API docs. I’ll explore ways to turn good API docs into great ones using examples in my upcoming post “Ten Extras for Great API Documentation”.

Error messages

When something goes wrong during development, fixing the problem without detailed documentation can become a frustrating and time-consuming process. To make this process as smooth as possible, error messages should help developers understand:

what the problem is;

whether the error stems from their code or from the use of the API;

and how to fix the problem.

All possible errors—including edge cases—should be documented with error-codes or brief, human-readable information in error messages. Error messages should not only contain information related to that specific call, but also address universal topics like authentication or HTTP requests and other conditions not controlled by the API (like request timeout or unknown server error).

This post from Box discusses best practices for server-side error handling and communication, such as returning an HTTP status code that closely matches the error condition, human-readable error messages, and machine-readable error codes.

Quickstart guide

Newcomers starting to implement your API face many obstacles:

They are at the beginning of a steep learning curve

They might not be familiar with the structure, domain, and ideas behind your API

It’s difficult for them to figure out where to start.

If you don’t make the learning process easier for them, they can feel overwhelmed and refrain from delving into your API. 

Many developers learn best by doing, so a quickstart guide is a great option. The guide should be short and simple, aimed at newcomers, and list the minimum number of steps required to complete a meaningful task (e.g., downloading the SDK and saving one object to the platform). Quickstart guides usually have to include information about the domain and introduce domain-related expressions and methods in more detail. It’s safest to assume that the developer has never before heard of your service.

Stripe’s and Braintree’s quickstart guides are great examples; both provide an overview of the most likely tasks you’ll want to perform with the API, as well as link you to the relevant information. They also contain links to contact someone if you need help.

Tutorials

Tutorials are step-by-step walkthroughs covering specific functionality developers can implement with your API, like SMS notifications, account verification, etc.

Tutorials for APIs should follow the best practices for writing any kind of step-by-step help. Each step should contain all the information needed at that point—and nothing more. This way users can focus on the task at hand and won’t be overloaded with information they don’t need.

The description of steps should be easy to follow and concise. Clarity and brevity support the learning process, and are a best practice for all kinds of documentation. Avoid jargon, if possible; users will be learning domain-related language and new technology, and jargon can instill confusion. Help them by making all descriptions as easy to understand as possible. 

The walkthrough should be the smallest possible chunk that lets the user finish a task. If a process is too complex, think about breaking it down into smaller chunks. This makes sure that users can get the help they need without going through steps they’re not interested in.

Twilio’s tutorials explain the most-likely use cases with sample apps in a wide variety of programming languages and frameworks. Universal topics

To implement your API, there are some larger topics that developers will need to know about, for example:

Authentication. Handled differently by each type of API, authentication (e.g., OAuth) is often a complicated and error-prone process. Explain how to get credentials, how they are passed on to the server, and show how API keys work with sample code.

Error handling. For now, error handling hasn’t been standardized, so you should help developers understand how your API passes back error information, why an error occurs, and how to fix it.

HTTP requests. You may have to document HTTP-related information as well, like content types, status codes, and caching.

Dedicate a separate section to explaining these topics, and link to this section from each related API call. This way you can make sure that developers clearly see how your API handles these topics and how API calls change behavior based on them. 

Layout and navigation

Layout and navigation are essential to user experience, and although there is no universal solution for all API docs, there are some best practices that help users interact with the material.

Dynamic layout

Most good examples of API documentation use a dynamic layout as it makes navigation easier for users than static layouts when looking for specific topics in extensive documentation. Starting with a scalable dynamic layout will also make sure you can easily expand your docs, as needed.

Single page design

If your API documentation isn’t huge, go with a single page design that lets users see the overall structure at first sight. Introduce the details from there. Long, single page docs also make it possible for readers to use the browser’s search functionality.

Stripe managed to present extensive documentation in an easy to navigate single page. Persistent navigation

Keep navigation visible at all times. Users don’t want to scroll looking for a navigation bar that disappeared.

Multi-column layout

2- or 3-column layouts have the navigation on the left and information and examples on the right. They make comprehension easier by showing endpoints and examples in context.

Clearbit’s three-column layout displays persistent navigation (table of contents) on the left, references in the middle, and code examples on the right. Syntax highlighter

Improving the readability of samples with syntax highlighting makes the code easier to understand.

The syntax highlighter in action on Plaid’s API documentation site.

If you’d like to start experimenting with a layout for your docs, you might want to check out some free and open source API documentation generators.

To learn about the pros and cons of different approaches to organizing your API docs in the context of developer portals, this is an excellent article by Nordic APIs.

Editing

All writing that you publish should go through an editing process. This is common sense for articles and other publications, but it’s just as essential for technical documentation.

The writers of your API docs should aim for clarity and brevity, confirm that all the necessary information is there, and that the structure is logical and topics aren’t diluted with unnecessary content. 

Editors should proofread your documentation to catch grammar mistakes, errors, and any parts that might be hard to read or difficult to understand. They should also check the docs against your style guide for technical documentation and suggest changes, if needed.

Once a section of documentation is ready to be published, it’s a good idea to show it to people in your target audience, especially any developers who haven’t worked on the documentation themselves. They can catch inconsistencies and provide insight into what’s missing.

Although the editing process can feel like a burden when you have to focus on so many other aspects of your API, a couple of iterations can make a huge difference in the final copy and the impression you make.

Keep it up-to-date

If your API documentation is out of date, users will get frustrated by bumping into features that aren’t there anymore and new ones that lack documentation. This can quickly diminish the trust you established by putting so much work into your documentation in the first place.

When maintaining your API docs, you should keep an eye on the following aspects:

Deprecated features. Remove documentation for deprecated features and explain why they were deprecated.

New features. Document new features before launch, and make sure there’s enough time planned for the new content to go through the editorial process.

Feedback. Useful feedback you get from support, or analytics should be reflected in your docs. Chances are you can’t make your docs perfect at the first try, but based on what users are saying, you can improve them continuously.

For all this to work, you will have to build a workflow for maintaining your documentation. Think about checkpoints and processes for the above mentioned aspects, editing, and publication. It also helps if you can set up a routine for reviewing your docs regularly (e.g. quarterly).

Following these best practices, you can build a solid foundation for your API documentation that can be continuously improved upon as you gain more insight into how users interact with them. Stay tuned for part two, where I give you some tips on how to turn good API docs into amazing ones.

http://ift.tt/2f83Bu0

[dustinwootenne]

The Ten Essentials for Good API Documentation

API documentation is the number one reference for anyone implementing your API, and it can profoundly influence the developer experience. Because it describes what services an application programming interface offers and how to use those services, your documentation will inevitably create an impression about your product—for better or for worse.

In this two-part series I share what I’ve learned about API documentation. This part discusses the basics to help you create good API docs, while in part two, Ten Extras for Great API Documentation, I’ll show you additional ways to improve and fine-tune your documentation. 

Know your audience

Knowing who you address with your writing and how you can best support them will help you make decisions about the design, structure, and language of your docs. You will have to know who visits your API documentation and what they want to use it for. 

Your API documentation will probably be visited and used by the following audiences. 

Developers

Based on their skills, experience, and role in projects, developers will generally be the largest and most diverse group. They’ll be using your docs in different ways.

At Pronovix, we started conducting developer portal workshops with our clients to help them learn more about what developers need and how to best support their work—and what they’re really looking for in API documentation. This is also supported by solid research, such as the findings published in Stephanie Steinhardt’s article following a two-year research program at Merseburg University of Applied Sciences.

Newcomers: Developers lacking previous experience with your API tend to need the most support. They will take advantage of quickstart guides that encourage them to start using your API—clear, concise, step-by-step tutorials for the most important topics, and sample code and examples to help them understand how to use it in real projects. If you can make onboarding pleasant for newcomers, they will be more likely to devote themselves to learning every nuance of your API.

External developers: Developers already working with your API will come back repeatedly to your docs and use them as reference material. They will need quick information on all the functionality your API offers, structured in an easy to understand way to help them quickly find what they need.

Debuggers: Developers using your API will encounter errors from time to time and use your documentation to analyze the responses and errors that crop up.

Internal developers: API providers tend to focus so much on their external audience that they forget about their own developers; internal teams working on the API will use the API documentation, as well.

These are just the most common use cases.

Decision makers

Decision makers like CTOs and product managers will also check out your API documentation and evaluate your API. They need to determine whether your API will be a good fit for their project or not, so it’s crucial to your business that this group can easily and quickly find what they’re looking for.

Other audiences

Although not as common, journalists, technical writers, support staff, developer evangelists, and even your competition might read your API documentation. 

Remember the purpose of documentation

The foundation of your API documentation is a clear explanation of every call and parameter.

As a bare minimum, you should describe in detail:

what each call in your API does

each parameter and all of their possible values, including their types, formatting, rules, and whether or not they are required.

Context-based structure

People won’t read your API documentation in order, and you can’t predict which part they will land on. This means, you have to provide all the information they need in context. So following the best practices of topic-based authoring, you should include all necessary and related information in the explanation of each call.

Context.IO, for example, did a great job documenting each of their API calls separately with detailed information on parameters and their possible values, along with useful tips and links to related topics.

Examples

In order to be able to implement your API, developers need to understand it along with the domain it refers to (e.g., ecommerce). Real world examples reduce the time they need to get familiar with your product, and provide domain knowledge at the same time.

Add the following to the description of each call:

an example of how the call is made

an explanation of the request

sample responses

Studies have shown, that some developers immediately like to delve into coding, when getting to know a new API; they start working from an example. Analysis of eye-tracking records showed that visual elements, like example code, caught the attention of developers who were scanning the page, rather than reading it line by line.  Many looked at code samples before they started reading the descriptions.

Using the right examples is a surefire way to improving your API docs. I’ll explore ways to turn good API docs into great ones using examples in my upcoming post “Ten Extras for Great API Documentation”.

Error messages

When something goes wrong during development, fixing the problem without detailed documentation can become a frustrating and time-consuming process. To make this process as smooth as possible, error messages should help developers understand:

what the problem is;

whether the error stems from their code or from the use of the API;

and how to fix the problem.

All possible errors—including edge cases—should be documented with error-codes or brief, human-readable information in error messages. Error messages should not only contain information related to that specific call, but also address universal topics like authentication or HTTP requests and other conditions not controlled by the API (like request timeout or unknown server error).

This post from Box discusses best practices for server-side error handling and communication, such as returning an HTTP status code that closely matches the error condition, human-readable error messages, and machine-readable error codes.

Quickstart guide

Newcomers starting to implement your API face many obstacles:

They are at the beginning of a steep learning curve

They might not be familiar with the structure, domain, and ideas behind your API

It’s difficult for them to figure out where to start.

If you don’t make the learning process easier for them, they can feel overwhelmed and refrain from delving into your API. 

Many developers learn best by doing, so a quickstart guide is a great option. The guide should be short and simple, aimed at newcomers, and list the minimum number of steps required to complete a meaningful task (e.g., downloading the SDK and saving one object to the platform). Quickstart guides usually have to include information about the domain and introduce domain-related expressions and methods in more detail. It’s safest to assume that the developer has never before heard of your service.

Stripe’s and Braintree’s quickstart guides are great examples; both provide an overview of the most likely tasks you’ll want to perform with the API, as well as link you to the relevant information. They also contain links to contact someone if you need help.

Tutorials

Tutorials are step-by-step walkthroughs covering specific functionality developers can implement with your API, like SMS notifications, account verification, etc.

Tutorials for APIs should follow the best practices for writing any kind of step-by-step help. Each step should contain all the information needed at that point—and nothing more. This way users can focus on the task at hand and won’t be overloaded with information they don’t need.

The description of steps should be easy to follow and concise. Clarity and brevity support the learning process, and are a best practice for all kinds of documentation. Avoid jargon, if possible; users will be learning domain-related language and new technology, and jargon can instill confusion. Help them by making all descriptions as easy to understand as possible. 

The walkthrough should be the smallest possible chunk that lets the user finish a task. If a process is too complex, think about breaking it down into smaller chunks. This makes sure that users can get the help they need without going through steps they’re not interested in.

Twilio’s tutorials explain the most-likely use cases with sample apps in a wide variety of programming languages and frameworks. Universal topics

To implement your API, there are some larger topics that developers will need to know about, for example:

Authentication. Handled differently by each type of API, authentication (e.g., OAuth) is often a complicated and error-prone process. Explain how to get credentials, how they are passed on to the server, and show how API keys work with sample code.

Error handling. For now, error handling hasn’t been standardized, so you should help developers understand how your API passes back error information, why an error occurs, and how to fix it.

HTTP requests. You may have to document HTTP-related information as well, like content types, status codes, and caching.

Dedicate a separate section to explaining these topics, and link to this section from each related API call. This way you can make sure that developers clearly see how your API handles these topics and how API calls change behavior based on them. 

Layout and navigation

Layout and navigation are essential to user experience, and although there is no universal solution for all API docs, there are some best practices that help users interact with the material.

Dynamic layout

Most good examples of API documentation use a dynamic layout as it makes navigation easier for users than static layouts when looking for specific topics in extensive documentation. Starting with a scalable dynamic layout will also make sure you can easily expand your docs, as needed.

Single page design

If your API documentation isn’t huge, go with a single page design that lets users see the overall structure at first sight. Introduce the details from there. Long, single page docs also make it possible for readers to use the browser’s search functionality.

Stripe managed to present extensive documentation in an easy to navigate single page. Persistent navigation

Keep navigation visible at all times. Users don’t want to scroll looking for a navigation bar that disappeared.

Multi-column layout

2- or 3-column layouts have the navigation on the left and information and examples on the right. They make comprehension easier by showing endpoints and examples in context.

Clearbit’s three-column layout displays persistent navigation (table of contents) on the left, references in the middle, and code examples on the right. Syntax highlighter

Improving the readability of samples with syntax highlighting makes the code easier to understand.

The syntax highlighter in action on Plaid’s API documentation site.

If you’d like to start experimenting with a layout for your docs, you might want to check out some free and open source API documentation generators.

To learn about the pros and cons of different approaches to organizing your API docs in the context of developer portals, this is an excellent article by Nordic APIs.

Editing

All writing that you publish should go through an editing process. This is common sense for articles and other publications, but it’s just as essential for technical documentation.

The writers of your API docs should aim for clarity and brevity, confirm that all the necessary information is there, and that the structure is logical and topics aren’t diluted with unnecessary content. 

Editors should proofread your documentation to catch grammar mistakes, errors, and any parts that might be hard to read or difficult to understand. They should also check the docs against your style guide for technical documentation and suggest changes, if needed.

Once a section of documentation is ready to be published, it’s a good idea to show it to people in your target audience, especially any developers who haven’t worked on the documentation themselves. They can catch inconsistencies and provide insight into what’s missing.

Although the editing process can feel like a burden when you have to focus on so many other aspects of your API, a couple of iterations can make a huge difference in the final copy and the impression you make.

Keep it up-to-date

If your API documentation is out of date, users will get frustrated by bumping into features that aren’t there anymore and new ones that lack documentation. This can quickly diminish the trust you established by putting so much work into your documentation in the first place.

When maintaining your API docs, you should keep an eye on the following aspects:

Deprecated features. Remove documentation for deprecated features and explain why they were deprecated.

New features. Document new features before launch, and make sure there’s enough time planned for the new content to go through the editorial process.

Feedback. Useful feedback you get from support, or analytics should be reflected in your docs. Chances are you can’t make your docs perfect at the first try, but based on what users are saying, you can improve them continuously.

For all this to work, you will have to build a workflow for maintaining your documentation. Think about checkpoints and processes for the above mentioned aspects, editing, and publication. It also helps if you can set up a routine for reviewing your docs regularly (e.g. quarterly).

Following these best practices, you can build a solid foundation for your API documentation that can be continuously improved upon as you gain more insight into how users interact with them. Stay tuned for part two, where I give you some tips on how to turn good API docs into amazing ones.

http://ift.tt/2f83Bu0

[maskaiot-blog]

MaskaMap was Awarded Make The World A Better Place App by Context.io

MaskaMap was Awarded Make The World A Better Place App by Context.io

A few weeks ago Return Path announced the winners of the Context.IO App Challenge Hackathon. There was only a limited amount of prizes awarded, far less than the number of impressive submissions received. We felt others were also deserving of recognition therefore the Context.IO team has created its own excellence awards.

So…Congratulations!!! We are pleased to announce that your application Mask…

[spinuplabs-blog]

Context.io Demo - List of Contacts

[Updated - This demo is using the contextio 0.4.0 rubygem] This is a quick and dirty demo of how to pull a list of contacts from your imap account using the Context.io API. First sign up for an account on http://context.io, then add an email account to it. Since Rails is one of the easiest ways to quickly prototype something, I am going to use it. I have made the assumption that you are working on a Mac with ruby and rails installed and working. First either create a new rails app or skip down one step to add to an existing app. Terminal rails new cio-demo cd cio-demo We need to include the Context.IO gem as well as the oauth gem. Gemfile # Context.io Specific gem 'contextio', '0.4.0' gem 'oauth' Once we save the Gemfile, we want to bundle those gems into our app Terminal bundle install I am sure there are other ways to do this, and maybe even better, but this is the way I did it for simplicity sake right now. We need to store our API keys and Email account key in an initializer. I am also setting up a persistent connection to the API. For this demo I am setting the email account id as a global variable, since we are using a single mailbox. Obviously replace the keys with your own. The keys can be retrieved from [https://console.context.io/#settings](https://console.context.io/#settings) config/initializers/contextio.rb # Global Context.IO Account ID $cio_acct = '[your_email_account_id]' #Context.IO Key contextio_key = '[your_api_key]' #Context.IO Secret contextio_secret = '[your_api_secretkey]' # Context.IO Persistent Connection Object $cio_connect = ContextIO::Connection.new(contextio_key,contextio_secret) We need to create our contacts controller. Terminal rails g controller contacts index show Then setup our index method. We are retrieving a list of contacts, then parsing the JSON and passing it into our view. app/controllers/contacts_controller.rb def index data = $cio_connect.list_contacts(:account => $cio_acct) @contacts = JSON.parse(data.body) end I am setting up the routes here, just so I can access the contacts controller without having to specify the method. I am also setting up the route for the show method, so we can pass an email address in the querystring. config/routes.rb get "contacts" => "contacts#index" get "contacts/index" => "contacts#index" match 'contacts/show/:email' => 'contacts#show', :constraints => { :email => /[^\/]+/ } Now launch your rails server and test. Terminal rails s You can access your contacts controller at [http://localhost:3000/contacts/](http://localhost:3000/contacts/) Now I setup a basic heading for our contacts/index view, and just echo out the data I am receiving from the API using debug @contacts. app/views/contacts/index.html.erb

List of Contacts

<%= debug @contacts %> You should see a bunch of data with two main pieces (query, matches). Matches is what we are interested in. Since the data returned for each contact is the same structure, I only want to echo out the first set. app/views/contacts/index.html.erb

List of Contacts

<%= debug @contacts["matches"].first %> Now I can see what data is being returned. For this demo I want to pull in the gravatar thumbnail, name and email address for each contact. I will print them out in a simple list. app/views/contacts/index.html.erb

List of Contacts

<% @contacts['matches'].each do |contact| %>

Name: <%= contact['name'] %> Email: <%= contact['email'] %> <%= link_to 'Contact Details','contacts/show/'+contact['email'] %>

<% end %> Notice the link to the contact details page. We need to create the contacts/show method which retrieves the information for the specific email address. app/controllers/contacts_controller.rb def show data = $cio_connect.get_contact(:account => $cio_acct, :email => params[:email]) @contact = JSON.parse(data.body) end Now we setup our show view. As we did above I want to create a simple heading as well as echoing out the data that is returned from the API call. app/views/contacts/show.html.erb

Contact

<%= debug @contact %> If you view the contact details page for a contact, you will see that we are only retreiving the data for a single contact. I want to show the gravatar thumbnail, name, last email recieved, last email sent and any emails address associated with this contact. app/views/contacts/show.html.erb

Contact

Name: <%= @contact["name"] %> <% if @contact["last_received"] %> Last Receipt: <%= Time.at(@contact["last_received"]).to_date %> <% end %> <% if @contact["last_sent"] %> Last Send: <%= Time.at(@contact["last_sent"]).to_date %> <% end %> Email Addresses:

<% @contact["emails"].each do |email| %>

<%= email %>

<% end %>

Now viewing our contact list at [http://localhost:3000/contacts/](http://localhost:3000/contacts/) we can click through to the contact details and see more information about each contact. We could even easier pull that contact list and invite them to use our app or compare it to existing users to find friends who already use our app. Context.io makes this data super easy to access and use in your app.