The Old Joel on Software Forum: Part 3 (of 5)

Where's the damn docs?

We're getting ready to release a developer library (designed for converting PDF's to plain [ASCII or Unicode ;-)] text easily, quickly, and with very little overhead...mostly for indexing and thin-client stuff), and I'm wondering if there are any particular pieces of developer documentation or help files that you would like to see in such paid-for libraries that you don't usually. Of course, we'll have the usual fare:

- API documentation
- Examples (how many, how complex?)
- a FAQ (pretty limited since this'll be our first release)
- links to a support board

What really pissed you off about the last library you purchased? (Please, no open source hit-and-runs, thanks.)

Don't hurt the gerbils
Monday, October 20, 2003

Here are a few things I've found helpful when using third party libraries:

1. WORKING example code, including make/prj/whatever files to actually build it in a range of environments.

2. Examples of interfacing to multiple languages/tools. ie, C, VisualBASIC, PowerBASIC, Delphi, Excel, etc.

3. A support message board which is actively used by the developers. The most excellent I've seen is at Digital Mars ... all developers could take lessons from Walter.

4. An honest assessment of the performance limitations of the product.

HeWhoMustBeConfused
Monday, October 20, 2003

Echoing the previous comment, what I want is:
1) A simple API documentation (the .Net documentation style is just about perfect)

2) Working code samples. I think the key here is iterative development - put your main code samples out, but keep the feedback door open and update them. I think the problem with a lot of code samples is that not everyone thinks like you do.
A big example - I've had to do a lot of work developing applications to accept phone calls via modem. In my experience, 99.9% of the code samples for modem interfaces are for *receiving* calls.
So I email you, we work it out, and (IMHO) you add the receiving code to your code bank.

3) Message board frequented by your development staff. You could break it into "support" and "community" if you're worried about chit-chat like this taking your devs' time.

Philo

Philo
Monday, October 20, 2003

Set up a cookbook style web page with "how tos" on it. A cookbook is a great way to show the capabilities of your API to potential developers.

Matthew Lock
Monday, October 20, 2003

> 1. WORKING example code, including make/prj/whatever
> files to actually build it in a range of environments.

Definitely -- and provide pre-built binaries.

Some of the Microsoft SDKs fall down here - they provide sample code that works, but not until you've built it.

If I am trying to get a feel for a new technology I don't want to have to stop to get the mechanics of my build environment set up to match the SDK's just to see a demo.

Rob Walker
Monday, October 20, 2003

Dotnet's working examples are awsome. Even though they use the same example in multiple places, it still helps to be able to paste something in your editor and compile and see it work.

Vince
Monday, October 20, 2003

have a mailing list

Monday, October 20, 2003

If you're planning support for .Net, include help files that integrate with the MSDN help. (I don't know the name of the format.)

I bought a third-party control from Janus Systems for VB.Net, and was impressed because:

(1) The help hooked into the MSDN "F1" help.

(2) The component shipped with good example files.

(3) The company had a good discussion board help system, with prompt responses from employees.

Robert Jacobson
Monday, October 20, 2003

A Wiki would be cool ..

Canuck
Tuesday, October 21, 2003

If you don't supply source code, an **unoptimised** debug build of the library with symbols and asserts is always useful. (If you're willing to supply a full PDB/super-Unix-whatever-format file with locals and type information, so much the better.)

(I say unoptimised, but I really mean whatever it takes to get a correct stack trace.)

Tom
Tuesday, October 21, 2003

1. Reference manuals that you can print, and browse off line, e.g., while riding the train to work. It used to be the norm - in the old days, Borland's _reference_ manuals were readable, cover to cover, with very little jumping needed.

Nowadays, it's nearly impossible. Most of the material is online only, with no order (or even possible order) whatsoever. And many help files are written in such a way that you can only look up details in them if you know what you're looking for.

2. Walk through tutorials, that start from _scratch_, and get to something working. Many tutorials do something like "take this 200k example C file that does x. Now change line 178 to read "blah". There, done." After going through this walkthrough, applying the knowledge requires digging up the 200k example file, and fixing it. Most developers that do that never clean up the 200k file, even if they only needed 20 lines out of it. (And the problem is not some "bloat" criterion - it's support costs. Every line of code is a liability).

Ori Berger
Tuesday, October 21, 2003

"Every line of code is a liability"

Including the ones that check all those return codes?

Oh. Wait. Wrong thread.

Tuesday, October 21, 2003

I agree with what Ori says about manuals. And check they are OK on both A4 and Letter, with no wasted pages caused by automatic conversion of HTML helps to PDF.

One thing you should also do is have webpagesfor the manual so you can put in the errata. The number of times I find that the code in the tutorial doesnt work because the sample file isn't exactly what it should be don't bear counting. Did improve my VB skills correcting the book though :)

Stephen Jones
Tuesday, October 21, 2003

Yes, including the ones that check those return codes.

Including the comments, and the documentation.

That's also why you should not have more documentation beyond what's really necessary - because, in the next update, you'll have to go through it and correct it all, and redo the screenshots, and a thousand other different things.

Every line of code is a liability, every page of documentation is a liability, everything the user sees is a liability. It's a liability you're generally willing to take in order to get your customer to part with his money, but it is a liability nontheless. You shouldn't take any more liability than you really need.

You don't get more money for a shipped product because you have another page in the manual or another line of code, or a feature no one uses.

Ori Berger
Tuesday, October 21, 2003

Thanks for all the comments and suggestions! Just to distill all the excellent points:

(a) Provide complete examples, as close to real life as possible. Forget about doing just 6 lines that touch the library's API.
(b) Provide complete, one-stop documentation. Something that compiles the API docs, examples, how-to's, current FAQ, and miscellaneous (i.e. known bugs, issues, workarounds, etc) into something you can read.
(c) Provide a useful and well-manned forum/mailing list/wiki dedicated to uses of the library.

BTW, this library is for Java, not .NET or VB/VC++. Although there's tons of PDF generators written in Java, there's currently a serious lack of tools/libraries for reading PDFs usefully (i.e. with a respectable performance profile that is realistic in a production environment). That's our niche for the product in question.

Don't hurt the gerbils
Tuesday, October 21, 2003

Another point:
Somehow (I don't know the best way) identify which version of your program the docs apply to. Especially sample code.

That way when somethng changes, and you forget/don't have time to change some sample code, the end user can figure it out. They realize 'hey they didn't have time to update this sample' instead of 'hey they're too dumb to even write code against their own library'.
If you have your samples in a wiki, you can even let the end-users suggest updates.

mb
Tuesday, October 21, 2003

For support, I'd skip the mailing list. Go with a newsgroup or a wiki, so you have a history of issues people can review.

Philo

Philo
Tuesday, October 21, 2003

Bad experience: The Java JDK documentation.

My god... the learning curve!

In order to use this object, you must understand this pattern and how we used it to solve this particular problem. Just when you think there's a sane way of doing something, it turns out that API is deprecated and you must now use an even more obtuse BuilderFactorySupplierFacadeBuilderFactory interface. But there's no example on how to actually use the damn thing in the API docs.

Someone mentioned it earlier, but I think it bears restating. As a developer, I *really* appreciate it when I can get documentation/support/opinions from people who know what they are talking about *AND THE INFORMATION HAS NOT BEEN SANITIZED BY MARKETING*. I can smell marketing BS a mile away. If an API performs slowly, tell me upfront. If I find out the hard way that a certain function is slow as hell, my reactionary instincts will tell me to go flame your entire library on some discussion board. You've wasted my time and YOU MUST PAY! (I usually get the better of my instincts, but there are plenty of developers who don't.)

Richard Ponton
Tuesday, October 21, 2003

Well, how about something more objective? Things like "not threadsafe" - no crime in that, there's plenty of desktop apps looking for what you're offering, but you'd better tell me up front if your library doesn't belong on a server.

"Only supports [x] languages" if we're talking a COM library, then what interface you export affects what languages can use your library. Again, no crime in only supporting VB6, but be honest. And NO GUESSING! You put that baby in a project, compile and run it. (yes, been burned on this one)

Those kinds of things.

Philo

Philo
Tuesday, October 21, 2003