I'm often encouraged to use company documentation standards when documenting my API/SDKs and programmer guides. I'm looking for rationale/examples that I can take to management to support my own experience that developers prefer documentation that doesn't look like a book.
Related, what is it that you DON'T like to see in this kind of documentation? (Something more specific than "all that's needed, but no more.")
I find web based documentation much easier to navigate through. It seems to preform much better than the PDF viewers I use. Plus I can bookmark pages and view the documentation in any browser. In my experience generating the web based documentation is much easier and quicker than a PDF. Most developers I have worked with seem more comfortable with web based than PDF when they are responsible with the generation of the documents.
I prefer web based documentation to PDF versions due to accessibility. It is much easier to link to different parts of the documentation on a web-based system. Think along the lines of Wikipedia and how you can quickly find very interesting topics by going through the links and references. Applying the same idea to documentation leads to easily finding the correct item you are looking for. In a PDF if you don't have the right idea of what you are looking for it may be near impossible to find anything useful. Using links you can at least start in the same ballpark and narrow your way from there.
I also find it easier to utilize bookmarks in the browser than PDF bookmarking. Typically people are more used to bookmarks in the browser than in PDF and they are much easier to manage.
Another benefit to web based versus PDF is that searching a web based system can be leaps and bounds better than a PDF. PDF isn't very friendly to present the results to you in any useful way, it goes linearly which is great if the result you need is in the next two or three results but gets unwieldy if you are starting on page 3 of a 1500 page PDF and the result is on page 1356.
The downfall of a lot of web based documentation seems to be that it tries to read like a book without the enhancement of search. I'm sure you have seen what I am talking about with previous and next chapter links at the bottom of the pages.
I prefer a book if I am going through to learn something since it will probably have a logical flow but if I am looking for help on a topic it is typically better to use something more non-linear.
One metric would be to have the managers search through a PDF for a topic and then do the same search using something else and see how much time it saves them to go for the second method. For most cases of what a developer would be looking for the second option will save a lot of time and help the bottom line which is probably what they are most concerned with.
I like both! They both have their strengths and weaknesses. If you use something like DOxygen or javadoc, you can have whatever output makes sense: a pdf "book" or a hyperlinked searchable website...
This is based solely on my Ph.D. research, but I would say that both are quite problematic, with PDFs likely being worth.
Let me explain: When you write an API and invest everything in documenting it, you are able to devote significant attention to each function in turn.
When somebody comes to use your API, or examines code that uses the API, the situation is different. The information needed to understand the call is delocalized - in order to examine it, one additional action must be taken. At a minimum, you have to hover over the call in the IDE to see the documentation (let's assume we're not dealing with polymorphism). In the worse cases, you have to go and open source code, or switch to a different application, or even open a book.
Programmers are naturally lazy and for good reasons - it is completely impractical for us to examine each and every call to learn everything about it. There are just too many outgoing calls, and the surprises are often not where we expect them.
Thus, as an API writer you must assume that the vast majority of calls will never be explored. How much will be explored is not fully outside your control (as an aside, I built a tool to assist with that), but there are ways to discourage an examination. The "best" way to discourage examination is to increase the cost or the latency by requiring an application switch, an active search in the browser, etc. I have seen dramatic differences and avoidance of documentation when a JavaDoc hover in Eclipse took more than 1/2 second to pop up. If the cost and delay is higher (e.g., switch to firefox, load PDFs) you are further decreasing the chances.
In other words, if your users say: "Am I willing to wait 25 seconds for acrobat to load up and then read the docs for the method after I find the page, or shall I just assume I understand what it does", they will go with the latter option. If you reduce the cost significantly (e.g., hyperlink in a browser on a second monitor) you are making the tradeoff more bearable.
I'd be happy to provide more info on this, if it's relevant to your team. Look up my contact info in my profile.
As for what should go in the docs, see my answer on "Tips for great JavaDocs"
If you do Java, you may want to take a look at my eMoose tool (yay for shameless plugs).
I wish I could remember the many webpage-based software documentation sets in which I have floundered for hours trying to find information among a dizzying maze of twisty little passages, all alike... (er, sorry, flashback there).
Here's an example from Microsoft for IXMLDOMDocument. Note that you get what I'd call a "shallow" view. All the methods and property names are there, but you get next to no information about them. What that means is that, instead of being able to read the core concepts of this COM interface on one page, I have to thrash back and forth between several pages. It's not so bad right now, but even a few months ago MSDN was miserably slow and took perhaps 5-10 seconds to download a page. Multiply that by the # of times you are browsing through pages just to see if a page is useful, and you get a HUGE slowdown in productivity and a loss of train of thought.
I much prefer Sun's approach for Javadoc. Here's the JTable interface. Notice it's got a "deep" view, including all the documentation for all methods and properties not found in JTable's superclasses. It's a large page, but once it's loaded, it's very quick to browse back and forth between methods and properties.
The printability of web documentation is also important. If I print out documentation, I can read it much faster and can browse back and forth much more quickly than if I try to read it online. The last time I tried to print out an MSDN documentation, the margins were all messed up and the text spewed off the right side of the page, and some of the multiple-page files were clipped so I only got a printout of the first page, minus a few words on the right side of the page. >:( >:( >:( Here's the GNU documentation for GNU awk, which comes in a number of formats automatically generated by a script. I get the printability of PDF, and the quick browseability of short HTML files.
The styles used in PHP and MySQL online documentation are both worth noting. (examples here for PHP and MySQL)