TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:SDK/API documentation From:John Stewart <john -dot- stewart -at- DLCC -dot- COM> Date:Wed, 21 Oct 1998 18:38:03 -0700
I'm looking for some *sage* advice on approaching an API/SDK
documentation project. I have worked on one SDK project (for a
Windows-based application), for which the programmers were using
AutoDuck to automatically build Winhelp files from the code comments. Of
course this required them to be reasonably disciplined about commenting
the code. I used the automatically generated files as a starting point,
and used Robohelp to integrate them with another set of files that
included overview material that I worked with the programmers to write.
This approach seemed to work well for both the programmers and myself.
I'm now looking at a project that seems to have some similar
requirements, but also some major differences. For starters, the project
will be implemented on both Windows and UNIX. The application was
originally developed as an off-the-shelf type application, and it's now
going to be implemented as part of an SDK so that individual sites can
customize it to their needs. This is what I've been told so far . . .
Apparently our company had a third party write the code that will allow
this customize-ability, which I guess essentially means they wrote the
API. We did not provide them with any specifications (so I'm not sure
how they knew what we wanted--ESP perhaps), and they in turn have not
documented the code that they wrote for us.
When I talked with our UNIX programmer, I started with what I'd learned
from the one other similar project I'd worked on--I asked if they'd
considered using an automatic documentation generation tool like
Autoduck, and asked about their code commenting practices. He said they
didn't need to comment the code "because it's object oriented." He
explained that that was the idea of object-oriented programming, so that
the programmers could "just look at the code and figure it out . . ."
It appears that we plan to release this so-called SDK (at least
initially) with no documentation, because no one in management, and none
of the programmers or designers, think it's necessary. From what little
experience I've had with this type of documentation, it seems important
to me. One concern I have is the technical writers being shut out of a
major project. Another is that after the initial release, someone will
realize that it *does* need documentation, and then it will be an insane
rush to get something out (and you can just forget quality . . .) Yet
another concern is that I could be wrong, and that it really isn't that
important to provide documentation for this type of product, so maybe I
should just not press the issue.
I've read through the TW list archives on API and SDK documentation and
found some valuable information. I've also searched the web and looked
at some nicely-done sets of SDK documentation. And, I've looked at the
DocJet site, which had a lot of useful information. So after all that
here are the questions still on my mind. What's the difference between
API and SDK documentation? (As I understand it, the API is usually just
a part of an SDK, as is some kind of documentation). Is it appropriate
to refer to documentation for a UNIX-based application as API doc, or is
that just appropriate for Windows? How could you approach documenting a
project like this given the lack of source documents or cooperation from
engineering (as described above)? How important is it to provide
documentation for an application like this as compared to user guides
and help for "boxed" applications? What experiences have other writers
had with this sort of project? And are programmers really necessary?
(Sorry about that last one . . .)