How Do You Like Your Documentation?

Generally speaking, what format do you like to see documentation in? PDF? FlashPaper? HTML? RTF? Text? Microsoft Word?

Personally, I prefer HTML. I can navigate and find what I need in my browser faster than anywhere else. I almost always have Javadoc in one browser tab and Macromedia LiveDocs open in another. If I need to be able to read documentation offline (on an airplane, for instance, since that’s about the only place I ever go anymore where I’m completely offline), I either save the HTML as a PDF, or preferably, download the HTML to browse locally. HTML prints well enough (although I almost never print anything), loads quickly, can be easily kept up to date, and generally fits into my workflow better than anything else.

In what format would you like to see most or all of the documentation you use on a regular basis, and why? (Don’t forget to take the poll!)

24 Responses to How Do You Like Your Documentation?

  1. I would love to see HTML documentation like that on MT, clean easy to read and navigate. However it should also include a link to download it in PDF or a compiled SWF for FP since it seems some people don’t like PDF.

  2. Steve Nelson says:

    Fusedocs inside of each file.

  3. JesterXL says:

    HTML that is easily printable.

  4. Locally available HTML is the best way to go. If I’m disconnected from the net, it’s always when I need to get on for something important. A table of contents/tree view is also very helpful. Printable isn’t important for me.PDF needs to die. It’s clunky and slow.Word is to platform dependent.RTF is acceptable, but not very usable.Flashpaper is cool but hardly usable.Plain text is ok but not for, say, a programming language where 100 different files would work best, and txt can’t link.Windows Help files are generally ok, but often suffer from some usability problems corrected by a web browser.

  5. Nolan says:

    In order of preference…1. an easy to follow physical book so I can fold pages down, carry it with me, etc.2. HTML that’s easy to print3. RTF4. PDF as a *last* resort. The lag and overhead of loading a plug-in or app to read docs isn’t always worth it. I may be developing on a fresh machine that doesn’t have PDF support. Or on a plain vanilla QA box that isn’t allowed any additional software.5. MS Word Docs. Only half of my Dev machines have any Office products installed. DOC files are often worthless to me.

  6. dave says:

    HTML all the way. Nothing is easier to browse. PDF & Flashpaper are too clunky. Printed materials are only good for reading… documentation means you need a specific piece of information, and HTML will probably get you there the fastest. Also, copy+paste is a necessity, and does not always work right in PDF & Flashpaper.

  7. Andy says:

    If i’m going to be reading on line then definately HTML, if I’m going to print then PDF.

  8. It would be really cool if you could download the live docs in both html and pdf format for local storage 🙂 I use HTML to integrate into my IDE and pdf’s to read when i’m away from the computer

  9. HTML, I particularly like the way that the HTML documentation was done for the Central SDK.

  10. Vui Lo says:

    Definitely HTML with printable CSS! I’m from the old school, reading is easier and better if the media is paper. However, for references, I find HTML is more effective than PDF.

  11. Bobby R. says:

    I would like to see the printable DevNet articles to Utilize FlashPaper instead of the html. Printing some articles that have the embeded frames for the code text doesn’t work well.

  12. HTML to viewPDF to printMicrosoft help files are damn quick though.

  13. HTML to viewPDF to printMicrosoft help files are damn quick though.

  14. Ohh yeah, almost forgot this one. I love the actionscript dictionary. Paperback is great! However, I would like it with spiral binding. I use the book a lot, but I’m sure if it stayed open to a certain page, I would use it much more 🙂 !!!!

  15. Tyler Silcox says:

    For documentation:HTML to view AND print…if you’re using Firebird.(FB cleans IE’s clock when it comes to printing)FlashPaper has some great possibilities, but as with most everything else Macromedia does, it has some severe limitations preventing it from becoming the clear winner.

  16. Kevin Graeme says:

    HTML is definitely preferred most of the time.I view other formats as secondary alternatives for special uses.FlashPaper is excellent at its one targeted thing: an on screen preview of a printed format. It’s not a replacement, it’s a supplement.PDF is a heavyweight. Cumbersome to load, but excellent for printing AND with searching capability in-document and throughout a collection of documents.RTF and MS Word are just rude.Plain text is annoying but so ubiquitous in support that it’s the acceptable cheapskate format.

  17. Mark Fuqua says:

    I hate to admit it…I like books. I like having the book open in my lab while I am looking at screen. Although I must say, when I purchase a $500 piece of software, I really do not like paying extra for the book. HTML is good for quick searches and is my second choice.

  18. Rachel Maxim says:

    I prefer HTML or regular MS help files. HTML is far easier to read and navigate than PDF. In fact I dread PDF documentation! Flashpaper is too slow for long docs. Please never, ever use Word docs.A good execution of HTML help is in Adobe’s Creative Suite products – Photoshop, etc. Sorry for mentioning Adobe. 😉

  19. Lola Lee says:

    I prefer my documentation all printed out, which illustrations where necessary. Also, I’d prefer not to have to print out my documentation on my printer or at Kinkos – would be great if software companies went back to supplying printed manuals for users.

  20. Lola Lee says:

    I prefer my documentation all printed out, which illustrations where necessary. Also, I’d prefer not to have to print out my documentation on my printer or at Kinkos – would be great if software companies went back to supplying printed manuals for users.

  21. Calvin Ward says:

    HTML is my primary preference, it seems to work the best in all situations.I absolutely dislike PDF or other proprietary formats.Word/RTF is better than PDF…

  22. MSPY says:

    I agree that HTML is the best format. It is the most open and easliy accessible format. MS Help is locked to Windows.However, those of you that don’t like PDF documentation because it is slow. It is the reader that slows it down. Apple’s OS X Panther comes with Preview which flies through PDF files.http://www.apple.com/macosx/features/preview/Just a sidenote, OS X makes it easy to make PDF files. Anything you can print can be saved as a PDF file without any special software.I like my MAC 🙂

  23. Jim Poyner says:

    I love pdf’s and html.

  24. David C. Menges says:

    From a reader’s perspective, I like to highlight / notate electronically. You can do this with PDFs if you have Acrobat (not Reader). There is a tool to highlight HTML – I’ll dig it up if anyone’s interested. I’ve used it with O’Reilly’s online books (Safari).However, if either the PDF or HTML is updated, I suppose that breaks the highlighting.