Abstraction-based versus instruction-based software document

A place to discuss the implementation and style of computer programs.

Moderators: phlip, Moderators General, Prelates

Posts: 86
Joined: Fri Jun 30, 2006 8:58 am UTC

Abstraction-based versus instruction-based software document

Postby heatsink » Wed Jun 24, 2015 8:07 am UTC

There is a mindset I see in some software documentation that bothers me a lot. Good documentation explains the observable behavior of software. In two words, I'd call that "abstraction-based". But a lot of documentation just consists of instructions on how to use the software in various situations. I'd call that "instruction-based", or maybe "frustrating".

I'm not sure what the cause is. Do some people prefer to read instructions and use cases over behavior specifications? Do authors settle for instructions because they're easier to write? Are some people really that bad at explaining things? Is instruction-based documentation merely a symptom of having a disorganized hodgepodge of functionality?

An examples of the difference is Maven's documentation versus Gradle's documentation. They are both used for building Java software. A few months ago, I was setting up my first Java project, which had an unconventional build procedure: manually download all dependences on computer A and transfer them to computer B, where the project is compiled. It seemed like a simple task, I've already done that kind of thing with Haskell/Cabal/hackage.

Maven's documentation is instruction-based. Users want to know things such as how to start a new project, how to add libraries, and how to compile their code, and Maven's documentation tells users how to do those things. Once you stray from the path Maven wants you to take, the documentation shows its inadequacy. How can you find out what are the dependencies of a piece of software? It doesn't exactly answer that; it says that you need to define at least 4 things for each dependency, leaving it as an exercise for the reader to understand why you need to define them and what may be needed beyond these 4 things. (Those 4 things are the group, artifact, and version to designate a name that uniquely identifies the dependency, and the scope to indicate for what steps of the build process the dependency is needed). In Maven's theory of software projects, the details do not merit explanation. Users write an XML project description, which is the interface to Maven-space where all the work happens. Users like me are out of luck. I probably sound frustrated.

Gradle's documentation explains the concepts that are relevant to build scripts. It explains that a dependency is an external file needed for building or running, and the most common kind of dependency is on artifacts from a repository, a repository is basically a collection of files identified by a group-name-version triple, and Maven and Ivy are two possible repository formats. These explanations segue into the corresponding features of Gradle's programming interface. For a new user setting up a build script that doesn't do everything in the default way, this documentation was very welcome. I chose Gradle for the build system.

So yeah, I'm wondering why some software documentation coaches you on what to do instead of explaining.

User avatar
Posts: 1806
Joined: Thu Sep 19, 2013 12:22 pm UTC
Location: London, UK

Re: Abstraction-based versus instruction-based software docu

Postby Quercus » Wed Jun 24, 2015 9:11 am UTC

I wonder whether it's to do with target audience (consciously or unconsciously). If you already know how to do the thing the software is for in general terms (maybe you used another software package for it before), then what you need to know is how the particular user interface works i.e. instruction-based documentation.

I know that I've found both sorts of documentation annoying at various times, depending on how much knowledge I have - it's frustrating to just be given a list of steps when I don't understand the concepts, equally it's frustrating to have to go through a detailed explanation of ideas I'm already familiar with just to find out what buttons to press/syntax to use in that particular package.

In my view the best documentation does both - it has a section of abstraction-based documentation for users who are unfamiliar with the ideas, and a section of instruction-based documentation for users who just need to familiarise themselves with the interface. Lots of python packages seem to do this (python chosen because it's what I know - other documentation may do this too).

Posts: 472
Joined: Wed Jul 27, 2011 3:13 pm UTC

Re: Abstraction-based versus instruction-based software docu

Postby Tub » Wed Jun 24, 2015 7:20 pm UTC

There are always users that don't want to learn the intimate details, they just want to know which things to click to get what they want. Maybe they don't (yet) care about build systems and just want to start writing code. Maybe they have a deadline and can't be bothered. Or maybe they're looking for quick instructions on deactivating the killbot without reading the very interesting chapter about the core design principles behind the innovative roboter control based on follicle gestures.

Both kinds of documentation can be useful. The first can save a lot of time if you don't care about the how. The second can enlighten you if you do, but takes more time to read.

User avatar
My HERO!!!
Posts: 5413
Joined: Tue Feb 20, 2007 12:49 am UTC
Location: The Googleplex

Re: Abstraction-based versus instruction-based software docu

Postby Xanthir » Wed Jun 24, 2015 10:23 pm UTC

You really want both. When I want to just download something and do something simple with it, I want some instructions that tell me what to do. When I'm trying to get deeper into the workings of something, I want a description of the actual behavior so I can reason about it. Projects with both make me happy; if they have one or the other only, I'm bound to be annoyed at some point.
(defun fibs (n &optional (a 1) (b 1)) (take n (unfold '+ a b)))

Posts: 207
Joined: Thu May 19, 2011 4:28 pm UTC
Location: Waterloo, Ontario

Re: Abstraction-based versus instruction-based software docu

Postby DaveInsurgent » Thu Jun 25, 2015 3:00 pm UTC

Could some of this be attributed to the use of documentation generating tools?

I prefer reading tests over docs of any kind.

Posts: 11443
Joined: Wed Jul 25, 2012 8:38 pm UTC

Re: Abstraction-based versus instruction-based software docu

Postby Tyndmyr » Mon Jun 29, 2015 10:47 pm UTC

Disclaimer: I hate maven. This is probably related to the documentation, and I'm likely more than a little biased.

I think there's a place for both abstract explanation of principles as well as instructions and examples. The best documentation has both. Go, find a board game. Crack it open. Look at the rulebook. Odds are *very* good that it sucks. Look through a few more, and find the one you like best. Board game rulebooks are short, and easily digested, far more so than programming frameworks. Model your coding documentation after the best of them.

For me, this distills to a very simple format. Let's do it with a board game.

#0. Contents of rules, with page numbers. Unless you can seriously fit everything on like, two pages...include this.
#1. Object of the game. Seriously, if you don't know what the end goal is, it'll suck to grok what the point of everything is. If you spent more than a paragraph on this, you did it wrong.
#2. Starting setup. Everyone has to set things up before they can progress to whatever's next. Use terse examples. Pictures, if possible.
#3. Turn order/how to play. This is your generic "these are your options, this is how they work" instructions.
#4. FAQ. This covers the strange interactions, the exceptions, the strange questions that come up when you're halfway through a game.

This translates to a program exceedingly well. It isn't complicated, and it works. You *need* both, but they should not be mingled together willy-nilly, with obscure technical details in the middle of some block of text you can't remember offhand when the question actually comes up.

Return to “Coding”

Who is online

Users browsing this forum: No registered users and 5 guests