Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Post History

60%
+1 −0
Q&A How can I write better code-based reference documentation for programming interfaces?

One possibility on why the readers didn't find the documentation helpful may be that they are unfamiliar to the API, and the reference documentation is the only documentation available. Reference...

posted 4y ago by celtschk‭

Answer
#1: Initial revision by user avatar celtschk‭ · 2019-12-15T18:24:13Z (over 4 years ago)
One possibility on why the readers didn't find the documentation helpful may be that they are unfamiliar to the API, and the reference documentation is the *only* documentation available. 

Reference manuals are there for the people who already are familiar with the API, and only have to look up the specifics of a function. It is almost always *not* suitable for people who are completely new to the API (an exception is e.g. a collection of math functions that are independent of each other).

This is a trap that especially projects using auto-generated reference manuals tend to fall into: They think they auto-generate reference documentation, therefore their API is adequately documented. But if your *only* documentation is the reference, then your API is *not* adequately documented.

As an example, take an imaginary graphics library.

If you look at the reference manual for the `drawLine` function, then you might find something like this:

> `void drawLine(Canvas c, GraphicsContext gc, Point start, Point end)`
>
>  Draws a line on a given canvas, using the settings from the given graphics context.
>
>  Arguments:
>
>    * `Canvas c`: The canvas to draw on. If Null, the function does not draw anything, but still updates the optional graphics context passed as second argument.
>
>    * `GraphicsContext gc`: The graphics context to use. If Null, the default graphics context of the supplied canvas is used. If no canvas is given either (the first argument is Null, too), the call returns immediately without doing anything.
>
>      The graphics context is used to determine the line style and drawing mode, and optionally the start and/or end point. On return, the `initialPoint` and `currentPoint` values of the graphics context are updated as described in the next two parameters.
>
>      See the type documentation for `GraphicsContext` for details.
>
>    * `Point start`: The point where to start the line. If Null, the `currentPoint` from the graphics context is used. If not Null, the value is stored in the graphics context as `initialPoint` on return.
>
>    * `Point end`: The point where to end the line. If Null, the `initialPoint` from the graphics context is used. On return, the `currentPoint` of the graphics context is set to this value.

Now if you are familiar with the graphics library, this documentation contains everything you need. But if you are not familiar with it, it will raise more questions than answers: What is a canvas, and how do I get one? What is a graphics context? What's that thing about `initialPoint` and `currentPoint`?

Now for sure, you can find all this in the reference documentation; you'll probably start by looking up the Canvas and GraphicsContext types, which will then lead you to functions that can be used to create those types and manipulate the GraphicsContext, probably involving other concepts like devices, leading you to the documentation of the corresponding types and functions for those … basically you'll have to discover the *structure* of the API on your own.

And that's where a programmer's manual comes in: This does not tell you every detail of the API, but it tells you the high-level aspects. It presents you the key concepts of the API in a logical and easy to grasp manner, tells you which steps you have to do in which order to get to the point where you can issue drawing commands, tells you abut the most important differences between drawing on the screen and drawing in a file, etc.

Basically, the programmer's manual allows you to get familiar with the API, while the reference library tells you the details of every single function and type, assuming you are already familiar with the API.

The two manuals are different because they are for different audiences. Someone new to the API will mainly use the programmer's manual. Someone familiar with the API will exclusively use the reference manual.

And most importantly, a programmer's manual *cannot* be generated from comments on the specific functions. Sorry, you'll not get to avoid the work.