manpage

Scarcity of Reference-Level Documentation?


My work tends to involve using tools and libraries from elsewhere, rather than providing this stuff for external consumption. But for what we do internally, "documentation" means providing information that concisely enumerates the functionality for others to use. By habit we tend to generate something that looks like UNIX man-pages, but I wouldn't say we consider that the ultimate format.

When it comes to the (mainly .NET) libraries and tools we use, however, this level of information seems to be pretty sparse, even for the "F1" type help from within the IDE.

Are we unusual in valuing accurate, concise API (and similar) reference material? Do others find it easily? Or do you find more value in tutorials, walk-throughs, and videos?

I would think this stuff would be the first and easiest materials to produce, because it's just about mandatory for having a controlled development-and-release process.

Currently a good example of this aggravation is with regard to ASP.NET MVC, but I don't mean to single it out as particularly egregious, just typical.


Solution

  • Forget MVC, I would like MS to produce decent documentation just for the regular .Net libraries. For as long as I can remember Microsoft documentation has been barely usable; bordering on crap.

    Every so often I accidentally hit F1 and go spelunking through the MSDN documentation. And, as always, after a couple minutes I realize that google is faster.

    As an example, just see how long it takes you to locate the datetime string format characters.

    I think this fact has carried on to most third party vendors.