Aspose.Pdf: Documentation Done Right
I spend so much time talking about how I feel let down by the documentation provided with the software that I review that it would be churlish not to comment on a company that does it right. So here it is:
Aspose.Pdf does it right.
I reviewed Aspose.Pdf for the September issue of Visual Studio Magazine, and one thing that impressed me was the product's documentation and help. Aspose provides a Help file that breaks down into two main sections. First, there is a Getting Started section that provides an overview of the package and what it does. The very first sentence provides what's often missing in these packages: a succinct description of what the product does in terms of "why you'd want to use it":
Aspose.Pdf for .NET is a .NET Component built to ease the job of developers to create PDF documents ranging from simple to complex on the fly programmatically.
The second section is a programmer's guide that provides detailed information on using Aspose. This section is in several parts. The first sections are introductions that assume you're not familiar with the basic technologies used by the package and provide essential background information. You're free to skip over these sections, of course, if you are familiar with the information.
The next part section is "scenario based:" it walks a developer through the basics of creating a "Hello, World" application with Aspose.PDF. This would probably be where most programmers would get started -- skipping the background material to see if they can get something working.
Aspose.PDF is smart enough to continue in that mode, organizing the information in the next few parts around typical scenarios. Rather than dumping the reader into an alphabetical list of classes and methods, information is organized by what developers would want to do: "Working with Sections," "Working with Images" and so on.
Aspose.Pdf has recognized that the typical developer question when starting to work with a product is not, "How do I use this class?" Instead, most developers want to ask the question, "How do I accomplish this task?" These parts don't consist of a hunk of code that you have to figure out. Instead, you get an overview of what the solution looks like, followed by the code you need.
Once you've gotten up to speed in Aspose.Pdf and have moved on to the point where you are asking "How do I use class ???', there's a an API reference that answers those questions.
It's just nice to see documentation done right. And darned unusual, also.
Posted by Peter Vogel on 10/08/2010