OT: Question for programmers, etc: APIs

[Magpel]

Waaaaaaaay OT:

 

I've been a writer my whole professional life, but never a tech writer before now. As part of my current tech writing job I am being asked to develop the documentation for an API developer's kit.

 

I know, in a vague sort of way, what an API is, but I honestly have no idea of what kinds of documentation typically accompany them, and in what forms.

 

My boss has asked me to look into the matter in a casual sort of way while I wait for him to say go.

 

So I'm starting here. Can any of you programmer types point me to a nice model online?

 

very thanks

[60hurts]

This?:

http://java.sun.com/j2se/1.4.2/docs/api/index.html

[Counterpoint]

The Java API is a good example, albeit HUGE!

 

An API is a group of function, classes, and or commands that can accomplish a group of related tasks. You can think of, for example, the set of HTML tags as an API. There are tags to create titles, tags to reference image files, tags to format text, tags to run scripts or applets, tags to break a page into a series of table cells, etc. There are a finite number of tags, each with its own purpose and syntax, and all of them work together to do a common job, i.e. format web content on a functional, pleasing page that can be displayed on any of a number of browsers.

[philbo]

 

Originally posted by Magpel Waaaaaaaay OT: I've been a writer my whole professional life, but never a tech writer before now. As part of my current tech writing job I am being asked to develop the documentation for an API developer's kit. I know, in a vague sort of way, what an API is, but I honestly have no idea of what kinds of documentation typically accompany them, and in what forms. My boss has asked me to look into the matter in a casual sort of way while I wait for him to say go. So I'm starting here. Can any of you programmer types point me to a nice model online? very thanks

 

 

Your lack of preknowledge is a valuable asset for a tech writer - - If you write the document so that it makes sense to you, it will necessarily be very clear, lucid and straightforward.

 

But APIs are, on the whole, pretty boring stuff to document. But documenting them is very important in terms of making the API useful to the programmer.

 

It is basically a dictionary of functions that the programmer can call, with detailed descriptions of the types of parameters you can pass to the function, what the function does, and what result (if any) the function returns when done.

 

Here is a link to the Skype API documentation:

https://developer.skype.com/Docs/ApiDoc/Skype_API_reference

 

(Skype, if you haven't heard of it, is an internet phone system)

[Magpel]

Thanks guys. I have never been disappointed when I've asked this kind of question here. And to those who might say, go search it out for yourself, my answer is: I'm doing that, too!

[GCDEF]

Just to add a bit more it stands for Application Programming Interface. It's provided so that programmers can interface with a system without actually having access to its source code. The Windows API for example, lets programmers write code to access and maniupulate the Windows operating system withtout having access to the Windows code itself.

 

I would disagree that lack of knowledge is a good thing. An API's documentation will be technical by nature and needs to be accurate and precise. A technical person isn't interested in what makes sense to a non-technical person. They want information that makes sense to them.

[Magpel]

 

Originally posted by GCDEF I would disagree that lack of knowledge is a good thing. An API's documentation will be technical by nature and needs to be accurate and precise. A technical person isn't interested in what makes sense to a non-technical person. They want information that makes sense to them.

 

 

This, unfortunately, makes sense to me. I relish the position in which I am the bridge between technical information and non-technical users. When it's "inside" commnication between technical audiences, that's when I feel acutely out of my element.

 

It was the same when I was faking my way as a medical writer; when the rhetorical situation was expert communication to a lay audience, I had no problems with masteirng the content; when it was expert-to-expert, I was on eggshells.

 

But my boss is very good about knowing my limits. Each thingsI've done on this job has been a combination of training and actual productive work. In this case, I'll probablyu end up being more of a document designer, a human version control system, an editor of course.

[plunky]

MSDN is full of API documentation for Windows, .Net, etc.

 

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/netstart/html/cpframeworkref_start.asp

 

People look at API's for two reasons: finding how specifically to use a particular piece and finding what particular piece to call. Make sure that you address the second part as well as the first. Code samples are great.

 

For example, the other day I was trying to figure out how to wrap my C# program as a Windows service. There is information on MSDN about how to use Visual Studio to do that, and about what classes to subclass, but after a few hours of searching I didn't find anything that said how to address it at a low level. I sighed, gave up, and just did it automatically in Studio like they suggested.

[Lee Flier]

+1 to what plunky said... I would really like to see more documentation organized by task. In other words you can look up a particular task you're trying to do and find the API functions that do it. Scrolling through an alphabetical list of a zillion functions to figure out which one does something in particular is a huge pain in the butt, but that's how a lot of documentation is.

[GCDEF]

Sample applications are probably more useul for showing how the pieces of an API all go together than documentation - at least to me.

[MorePaul]

I tend to agree - code samples are good

 

I think that may tie in with what Philbo was expressing -- maybe not so much lack of "knowledge", but lack of "familiarity"

 

After a couple of revs -- you know how it goes...not only do the coders, but the whole production team can get sort of "used" to the stuff and there gets to be slang and assumptions and just a general "way it works" philosophy developed.

 

That often doesn't get properly expressed in just paramter lists and general functional description and then it winds up like obscure golf rules where the statements are definitive, but the concept is still ambiguous ("now how am I supposed to use this?" / "but what the hell *IS* that switch for"?)

 

"show me" can also make for a great validation

-that the lists and the sample code agree

-QA can examine it for holes...error/exception handling, behavior around boundary conditions are all thought out

 

all that good stuff