Supersonic Man

August 17, 2016

will there ever be a material to replace steel?

Filed under: science!,the future!,thoughtful handwaving — Supersonic Man @ 12:14 pm

This post has been promoted to my website, here.

 

Advertisements

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.

Blog at WordPress.com.