Scarcity of Reference-Level Documentation?

Question

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.

Answer 1

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.

Answer 2

Different types of documentation are appropriate (and necessary) for different usage.

• When you need the broad scope of how to use a technology, a video can give you the 10,000ft view of its capabilities. But these rarely show readable examples of API usage.

• When you need to put together a basic project using that technology, a step-by-step tutorial is good. But these don't show you exotic cases or best practices; they show only one scenario of using the technology.

• When you need to learn best practices for designing a solution with that technology, or ways to integrate with other technology, then task-oriented documentation is best.

• When you're mostly familiar with the technology but you just need a reference for method signatures and such, then API docs are appropriate. These may be integrated into an IDE.

There is always a dearth of effective documentation. ASP.NET MVC may be one example, but it's not much better in the Java world. Yes, Javadoc reference material is available online, but many entries are trivial or placeholder text. API reference docs in general are inadequate to explain how best to use each given class and method in the context of application design.