[Framers] OT-Documenting APIs

Thu Nov 23 11:00:48 PST 2017

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" <Jeff.Coatsworth at jonasclub.com>
To: "An email list for people using Adobe FrameMaker software." 
<framers at lists.frameusers.com>
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.com at 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. 
><framers at lists.frameusers.com>; Rick Quatro <rick at rickquatro.com>
>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.
>>rick at frameexpert.com
>>585-366-4017
>>
>>
>>
>>-----Original Message-----
>>From: Framers
>>[mailto:framers-bounces+rick=rickquatro.com at lists.frameusers.com] On
>>Behalf Of A Craig
>>Sent: Wednesday, November 22, 2017 3:22 PM
>>To: framers at lists.frameusers.com
>>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:
>>acraig at shaw.ca <mailto:acraig at shaw.ca>
>>
>>
>>
>>Alison Craig
>>
>>
>>
>>_______________________________________________
>>
>>This message is from the Framers mailing list
>>
>>Send messages to framers at lists.frameusers.com 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 listadmin at frameusers.com
>>
>>_______________________________________________
>>
>>This message is from the Framers mailing list
>>
>>Send messages to framers at lists.frameusers.com 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 listadmin at frameusers.com
>>
>
>_______________________________________________
>
>This message is from the Framers mailing list
>
>Send messages to framers at lists.frameusers.com 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 listadmin at frameusers.com
>_______________________________________________
>
>This message is from the Framers mailing list
>
>Send messages to framers at lists.frameusers.com
>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 listadmin at frameusers.com