Hi Allison.
I've done a fair bit of API documentation, so feel free to ask me
questions.
The thing to remember is that basically an API doc is a cookbook. You
are providing the recipe and cooking instructions.
Most APIs these days are in some variant of XML (XML, YAML, YANG, etc.),
so being comfortable reading XML is a good start. W3schools has really
good reference material.
The other big thing is being able to read the source material and parse
it out.
XSD files are often used for these, but so are .yang and .json files.
yang.org and json.org have good references.
There are two significant areas for TWs in the source.
1) the Description section. This should clearly explain what the
element being described does.
2) the criteria section. This is basically everything else in the
element description. While some programmers are really OCD about doing
a complete set, others are lazy (or have been distracted).
At a minimum, you need to check for
* name
* type (uint, date, string, etc.)
* units (if required)
* optional/required
* values and restrictions This can get broken out as min/max values,
default, special values (such as -1), etc. These may be separate items
or a single item. You will often find this information buried in the
description, which is (IMO) not correct.
---
Depending on your application, there may be other types of values (for
example a mapping app might have directions), a financial app might have
currencies, etc.)
Note that the "type" may be something your dev team has cobbled up. If
so, you will need to find the file that they defined the type and then
locate the definition. (usually with a defType statement)
If you are doing RESTful APIs, check out
https://gist.github.com/iros/3426278
If you can pick your own tools, then grab a copy of Notepad++, if only
to use it as a scratch pad.
Once you have all tee information, then you need to work with your PM do
determine how much reference information you need to provide. Much of
this (as always) depends on the target audience. I've done really basic
stuff for experts, and full-on "this is what REST is and this is what a
.yang file looks like" material. At the very least, you need to provide
information on how the users (usually developers, but not always), will
connect to your system, what files are required, what correct out put
will look line and so on.
That should get you started.
------ Original Message ------
From: "Jeff Coatsworth" <[email protected]>
To: "An email list for people using Adobe FrameMaker software."
<[email protected]>
Sent: 11/23/2017 7:03:42 AM
Subject: Re: [Framers] OT-Documenting APIs
Write the Docs has a Slack channel and a forum under their umbrella
(along with an annual conference and meetups all over the world).
-----Original Message-----
From: Framers
[mailto:framers-bounces+jeff.coatsworth=jonasclub....@lists.frameusers.com]
On Behalf Of Shmuel Wolfson
Sent: Thursday, November 23, 2017 5:03 AM
To: An email list for people using Adobe FrameMaker software.
<[email protected]>; Rick Quatro <[email protected]>
Subject: Re: [Framers] OT-Documenting APIs
Are www.writethedocs.org and writethedocs.slack.com the same?
On 22-Nov-17 10:26 PM, Rick Quatro wrote:
Hi Craig,
You might want to check out:
http://www.writethedocs.org/
Rick Quatro
Carmen Publishing Inc.
[email protected]
585-366-4017
-----Original Message-----
From: Framers
[mailto:[email protected]] On
Behalf Of A Craig
Sent: Wednesday, November 22, 2017 3:22 PM
To: [email protected]
Subject: [Framers] OT-Documenting APIs
I'm writing the list because I hope someone here can answer my OT
question.
I'm currently doing contract work while I search for a new full-time
job.
The problem (for me) is that a *lot* of Tech writing jobs here in the
Vancouver, Canada, area include documenting APIs. Unfortunately, I
have zero experience in this area.
Given this fact, I'm wondering if anyone knows of an online course(s)
I could take to how to do this.
If anyone has any suggestions, feel free to answer me off-list:
[email protected] <mailto:[email protected]>
Alison Craig
_______________________________________________
This message is from the Framers mailing list
Send messages to [email protected] Visit the list's
homepage at http://www.frameusers.com Archives located at
http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to [email protected]
_______________________________________________
This message is from the Framers mailing list
Send messages to [email protected] Visit the list's
homepage at http://www.frameusers.com Archives located at
http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to [email protected]
_______________________________________________
This message is from the Framers mailing list
Send messages to [email protected] Visit the list's homepage
at http://www.frameusers.com Archives located at
http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to [email protected]
_______________________________________________
This message is from the Framers mailing list
Send messages to [email protected]
Visit the list's homepage at http://www.frameusers.com
Archives located at
http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to [email protected]
_______________________________________________
This message is from the Framers mailing list
Send messages to [email protected]
Visit the list's homepage at http://www.frameusers.com
Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to [email protected]
