Sucky docs are just frustrating

Since my move to OpenSource JavaScript frameworks, libraries, modules, etc. I spend a lot of time looking at the documentation for whatever it is I’m working on. Some docs are really good. They give a description, example, what something returns, what it expects as parameters, etc. However some are really bad. They define the name of the function/property/whatever but they don’t say what the hell it does. Take this example from the nodejs documentation for the ‘fs‘ module:

<rant>

So… looking at the above screen shot, what does fs.unlink and fs.unlinkSync do? I know that it will delete the path provided just from reading how to do things elsewhere, but if I didn’t know that, how would I discover what it does? This is a prime example of how NOT to document an API.

</rant>

So, if you’re creating documentation for your project, please for the love of god document it well. Until next time…. Happy Coding.

Share This:

  1. The documentation for everything sucks. Recently been using Mailchimps api, and while mostly good, it’s let down in small things, like exactly what format timstamps are in. They don’t actually tell you, andbthenthe actualitybis different to the documentation. Xero the same, they describe stuff that doesn’t work. Notes doco, too, often fails to explain exactly what something does. Notesdatetime.isdst is unclear as to whether DST is enabled for the object regardless of the current value, or just whether the specific value it has now has been adjusted for applicable DST or not. I could go on……

Comments are closed.