Who

Good Documentation is Useless

24 September

Do you ever find yourself reading technical docs like these:

LoggerFactory

CreateLogger(String)
Creates a Logger instance. 
AddProvider(LoggerProvider)
Adds a LoggerProvider to the logging system. 
AddLoggerReference(LoggerReference)
Adds a LoggerReference. 
TypeId
Type identifier. 
LoggerReferences
Logger references. 


I do.  And it seems like I find docs like these all the time.  Here’s what happens:


I read them,
blink twice,
question how the fuck somebody got paid for that,
then leave to look for something actually useful. 


It’s shit. 


Beyond the names themselves these docs add exactly this information and no more:

  1. The Logger created by CreateLogger is an “instance”. A meaningless word this time in this instance. 

  2. AddProvider adds something to the “logging system”. It’s already describing a specific function within the “logging system”.  It fucking better add something to the “logging system”, and that thing better be called a “Provider”, too. 

  3. The abbreviation “Id” stands for “identifier”. Not even Sherlock would have figured that out. 

Exactly none of that was useful. If you already knew what the pieces were, you didn’t need the docs. If you didn’t already know, the docs didn’t help.  Useless. For everybody. 


Write useful docs, not crap like this.