An API writer is a part of API ecosystem and creates API guides for better understanding of an API. To get into this role, you must be ready with your safety gears to play with live wires – APIs.
For a user guide or online help, a technical writer needs to be familiar with its application and the tools to generate the help. While an API writer burns their hand to know in-and-out functionality of an API, jumps into the codes, reads through API specifications and user stories (in case of agile project), and analyses the traces of an API. API guide comes in a raw format – just like a tomato without any garnishing, whereas online help comes with much glamour – tomato in salad.
Mostly, developers are main audience of API guides. They refer it to know about the API specifications, where they mostly look for the base path of APIs and resource URIs. In addition, users can also view the list of methods that are applicable to a request and their payload values, which is available in a code snippet. The parameters and error code descriptions are also some extra information available in the API guide.
You need to update your guides as of when an API story pass through the scrum board and deployed on pre-production and production servers. In between, get your document reviewed from SMEs and publish it for your users.
You need to assist in onboarding of developers in developer portal. Where they become part of API ecosystem and interact with APIs using their own Apps.
So, your role is not only restricted to writing API guide, but also read through the black-and-white codes and troubleshoot developer queries.
Let me clarify on the type of developers available in the API ecosystem. First, one who create APIs and second who access API resources. API guides are mainly catered for the latter.
Don’t get upset if you get only Microsoft Word for writing API guides. Gear up with Swagger – a way to describe APIs through JSON and YAML schemas.
Let’s have a reality check!
Architect provides the API specifications in the API ecosystem. These specifications cover most of the API knowledge areas in bits and pieces. The presentation and language are not much of importance when presented in a Swagger tool. Therefore, need for an API writer is minimum or not needed to create API guides.
However, you can buy food for yourself by creating demand in the API ecosystem – presenting clear and concise information about the APIs, having some hands on coding, and creating YAML files for the APIs.
For a user guide or online help, a technical writer needs to be familiar with its application and the tools to generate the help. While an API writer burns their hand to know in-and-out functionality of an API, jumps into the codes, reads through API specifications and user stories (in case of agile project), and analyses the traces of an API. API guide comes in a raw format – just like a tomato without any garnishing, whereas online help comes with much glamour – tomato in salad.
Mostly, developers are main audience of API guides. They refer it to know about the API specifications, where they mostly look for the base path of APIs and resource URIs. In addition, users can also view the list of methods that are applicable to a request and their payload values, which is available in a code snippet. The parameters and error code descriptions are also some extra information available in the API guide.
You need to update your guides as of when an API story pass through the scrum board and deployed on pre-production and production servers. In between, get your document reviewed from SMEs and publish it for your users.
You need to assist in onboarding of developers in developer portal. Where they become part of API ecosystem and interact with APIs using their own Apps.
So, your role is not only restricted to writing API guide, but also read through the black-and-white codes and troubleshoot developer queries.
Let me clarify on the type of developers available in the API ecosystem. First, one who create APIs and second who access API resources. API guides are mainly catered for the latter.
Don’t get upset if you get only Microsoft Word for writing API guides. Gear up with Swagger – a way to describe APIs through JSON and YAML schemas.
Let’s have a reality check!
Architect provides the API specifications in the API ecosystem. These specifications cover most of the API knowledge areas in bits and pieces. The presentation and language are not much of importance when presented in a Swagger tool. Therefore, need for an API writer is minimum or not needed to create API guides.
However, you can buy food for yourself by creating demand in the API ecosystem – presenting clear and concise information about the APIs, having some hands on coding, and creating YAML files for the APIs.
No comments:
Post a Comment