Supersonic Man

August 6, 2016

pseudo-documentation

Filed under: Hobbyism and Nerdry,Rantation and Politicizing — Supersonic Man @ 8:09 am

In my occupation as a coder, I have to read a lot of technical documentation in order to use existing software components.  And sometimes that documentation can be frustratingly incomplete or unavailable, but to me the worst situation to encounter is what I call pseudo-documentation.  It’s abundant out there.

I will give you a little example of what that’s like.  Let’s say you just encountered a line of code like this:

myThingy.FrabnicateZinxer(Zinxer.Load("arf"));

You have no idea what this does, so you look it up, and this is what you find:

Thingy.FrabnicateZinxer

Frabnicates a Zinxer for an instance of Thingy. If successful, the Zinxer will become frabnicated for this Thingy. If the Zinxer was already frabnicated for another Thingy, the new Thingy will be placed first in the frabnication order of the Zinxer. If it is already frabnicated for this Thingy, no change takes place.

Signature:
public void FrabnicateZinxer(Zinxer zinxerToFrabnicate);

Parameters:
zinxerToFrabnicate – the Zinxer which is to be frabnicated for this Thingy.

Return value:
none

Exceptions:
NullParameterException – a null value was passed as zinxerToFrabnicate.
InvalidOperationException – the Zinxer passed as zinxerToFrabnicate is in a nonfrabnicable state.

Example:
Thingy thingy = new Thingy();
Zinxer zinxer = Zinxer.Load("brb");
thingy.FranbicateZinxer(zinxer);

See also:
Zinxer class
Thingy class

 
. . . You see what the problem is?  The documentation covers all aspects of what needs to be available in reference material, but you learn nothing by reading it.  It labels the parts but says nothing about what they actually do.  All it tells you is what you had already assumed just from seeing the name — that some unknown thing undergoes some unknown process.  The only new knowledge you come away with is maddening hints of ways it might go wrong, none of which have any explanatory context.

There are many outfits which produce crap like this, but Microsoft may be the worst.  Their tech writers don’t seem to have any supervision by anyone who checks the quality of the work.  Even when they’re writing at length in tutorial or instructional form, the result is often full of gaps and omissions where crucial pieces of context are missing, not to mention inconsistencies which undermine your chances of piecing together anything definite.

Advertisements

2 Comments »

  1. It kind of sounds like if a teacher said, “Use arachnid in a sentence.” And the student said, “The arachnid was a big deal.” That doesn’t tell you what an arachnid is.

    Comment by Lois Rosewood — August 6, 2016 @ 12:49 pm | Reply

  2. It is a rare individual who can write both good English and digital language. I wonder if there aren’t two parts of the brain involved; one develops or the other does, not both.

    Comment by gwynn o'neill — August 6, 2016 @ 11:30 pm | Reply


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Blog at WordPress.com.

%d bloggers like this: