Post History

Source: https://writers.stackexchange.com/a/11012
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

As a user, you use API for certain purposes. You have certain goals you want to achieve, and the API is a tool that should help you achieve them.

Your problem is, how to achieve these goals.

Think of API "hardwareToolbox", which is a common toolbox in your garage. There's a hammer, there's a set of wrenches, a screwdriver, there's a hacksaw and an electric drill. Each of them are classes that have their methods. You also have nails, screws, screw anchors, etc. (all provided by right Factory objects.)

You want to hang a picture on the wall. You have no clue how to do it.

The right procedure is to drill the hole in the wall, put a screw anchor in, using a hammer, and then screw a screw in. As the user you know you need a screw in the wall, but not much more beyond this.

Now let's look at your documentation.

      Class Electric_hammer_drill. Makes holes.
      @methods: drill, hammer.
    
      method drill: Makes holes in material that doesn't need hammering
      @params: tool, depth, direction
      @return: hole
    
      method hammer: Makes holes in material that needs hammering
      @params: tool, depth, direction
      @return: hole
    
    
      Class Hammer. Applies kinetic impulse to objects.
      @methods: hit.
    
      method hit: Applies kinetic impulse to object
      @params: object, strength, location
    
      Factory Screw_anchor: anchors screw to wall.
      @params: inner_diameter, outer_diameter, length
    
      Factory Screw: Binds things together
      @params: diameter, length.
    
      Class Screwdriver: Turns screws.
      @methods turn
    
      Method turn: Turns screw.
      @params: direction, rotations, hole, screw.
    
      ...and about 40 other tools and items you don't need.

Do you see where I'm going?

The user will deduce: I need a screw in the wall. To move screw I need screwdriver. Screwdriver requires hole. To make hole I need the drill. By a lot of trial and error I discover wall requires hammering, and a masonry bit for a tool to obtain a hole. (or I just drill one with wood bit, cursing the inefficiency of the API.) Then I try to fit the screw and it doesn't hold, and I'm all frustrated.

What you need is use patterns. Examples. PURPOSES.

Think of this.

      method drill: Makes holes in material that doesn't need hammering, like wood, metal or plastic. Check table@... for right tool for the material.
      @params: tool, depth, direction
      @return: hole
    
      method hammer: Makes holes in material that needs hammering, specifically concrete. Use masonry bit for a tool.
      @params: tool, depth, direction
      @return: hole
    
      Factory Screw: Binds things together. Requires hole of matching diameter in flexible materials like wood, threaded hole in metal, or a screw anchor of matching inner diameter in concrete.
      @params: diameter, length.
    
      Factory Screw_anchor: anchors screw to wall. Requires a hole of outer_diameter in concrete type material. Provides hole of inner_diameter in flexible type material. Should be installed using a hammer. Typical use is allowing installing screws in walls.
      @params: inner_diameter, outer_diameter, length

Basing on such a documentation the user should be able to deduce the correct procedure for installing the screw for the picture frame. It contains purposes, actual practical requisites (as opposed to formal), hints on how to use given tools, when to use them, and if they have specific requisites in specific situations.

Even better is to provide rich examples, but these are to appear outside the direct function documentation. Nevertheless, besides writing **what** a function does, write its **what for** (purpose - why'd you ever need that result), **actual requisites** (not just a list of params it _might_ take, but params it absolutely _needs_, typical **usage patterns** (hammer concrete, drill all the rest, a screw anchor needs to be driven by a hammer) and **caveats** (screw won't hold in raw concrete, needs screw anchor.)

Just telling _what_ a function does is not helpful if I never know _why_ it does it, and _how to get it to do it right_.

Original score: 1