This is one of those posts where I've pretty much decided what I'm going to do anyway, but would like input from other people.

I'm writing documentation for a project I find to be quite complex. I've always run into problems documenting in HTML in the past such as parsing and making it look how I want, not spending enough time on the actual content and flow of the document. I recently decided to switch to PDF using OpenOffice.org Writer and I've come up with 60 pages of amazing (-looking) documentation over the last few days. It looks quite a bit more professional than the HTML I've come up with and it's a whole lot easier to read and to write.

The main drawbacks I see are lack of availability "right there" over the internet and the inability of some programs (such as KPDF and KGhostView) to copy text from the document for pasting into source code. An alternative to that would be to include source code files for examples, but my document currently has endless 4-line snippets to explain things.

As a developer, do you appreciate readability and convenience over quick access over the internet, possibly at the expense of being able to copy and paste? I'm open to other suggestions but I refuse to create another poll. Thanks.
ta0kira

As a user of documentation I detest pdf. When using Google I always choose "View as HTML" when Google gives me that option for a pdf file.

When I write documentation I first write it as text in a text editor. Then I sometimes transfer it to html. Once a project leader asked me to rewrite some of my documentation from HTML to DocBook XML which Gnome uses as a standard documentation format.

http://tldp.org/LDP/LDP-Author-Guide...dversions.html

I did it and swore that I would never use DocBook XML again. It was extremely slow and tedious. I suppose that I would reconsider if there was a decent DocBook XML editor.

-----------------------
Steve Stites

I've been using latex for most everything over the past year and a half. Produces awesome looking documents, and lets you focus on the content while writing.

EDIT: Creating PDFs from latex files is easy and is what most people use as the presentation format for their tex docs

+1. I never just look at 1 page in documentation, but usually have 5+ different tabs in my browser open. PDF just isn't good for random access (by a human, that is), but HTML is pretty good.

However, when I plan on reading the majority of some documenation (more like a reading a book), I usually print it off, and PDF stuff just does better for that... since WYSIWYG on the printer.

An original format like docbook while maybe harder to write for initially will allow either html or pdf documents or info files to be produced.

I'll often download source code for a package and produce the pdf version of the manual or book from the texi source used to produce the info files. One example is "GAWK: Effective Awk Programming" which I produced the pdf version and then printed that off.

HTML sucks for printing. PDF file based documentation is easier to download from a website. If you are careful in not using funky fonts and formatting, cutting and pasting from pdf files is not a problem. However if you produce a pdf document by printing to a pdf file that may produce a poor pdf file, almost as bad as a fax image. I hate trying to read a pdf document where the diagrams are over compressed jpeg files instead of drawings that you can zoom in on.

I agree with everything that's been said, but I think I should have explained what I'm doing a little bit more.

The document I'm currently working on is really 2 user's guides in one. The first is for administrators of the system who needn't have any programming experience, but need to know how to use a shell. The second is for extension developers, but it's mainly just a quickstart so they know what in general needs to happen to create extensions, as well as a few key headers and functions.

I have a section at the very end of the current document reserved for the API reference. I've been ignoring it because I know it won't work in a PDF file. I think something mentioned above will be more suitable, probably with the help of DOxygen.

The administrator's and extension developer's quickstart guides cover fairly abstract information that's necessary in order to understand the project well enough to perform either function. I think I intend both to be used as an intro to the project (well, currently 74 pages worth) and then as a quick reference when an administrator or developer need a reminder about the internal functionality of the system. I've avoided as much actual code in the document as possible, but will probably create a "usable" API reference and manpages for the shell commands.

So I guess I've decided to go with man/info for the shell commands and something in line with the comments above (which I haven't decided on) for the API, but I do think I need a colorful, graphical, highly-formatted intro document for both administrators and developers. I've already ruled out HTML and Latex because of the "highly-formatted" requirement. Are there any other document formats that allow images, diagrams, tabs, colored/shaded text with borders, hyperlinks, etc. that actually show up as I've written them for everyone? Thanks.
ta0kira

PS The reason I want the intro guide(s) to look extremely professional is this is a fairly complex system that requires quite a bit of effort to understand well enough to use, and even more to develop for. I'd rather people not discard it before knowing what it's capable of because the document came out either too primitive-looking or misaligned.

PPS Sadly, the project is actually a "facility" that does nothing dazzling on its own. It will require the help of outside developers to create useful extensions for it to create large-scale modular applications. I will probably have to create a showy system of my own extensions to get peoples' attention, but that's an entirely different issue...

pdf is still proprietarily created by adobe and their later version may not be supported by linux distributions.

So while you may have no problem, I would go with HTML every time.

Also, pdf does'nt always read well - particularly when it is created by some publisher who might put 2 columns across some arbitrarily (for the end user) decided page size. An A4 print sheet does'nt for instance render well on a screen. User would have to keep scrolling back and forth and so on.

End

Well, here's the status. The PDF thing was great for getting the ideas out of my head, but now I don't even like updating it. Here's the plan.

I finally got around to figuring out the deal with CSS and that + XHTML is exactly what I need. It pretty much does exactly what I asked for in a previous post in this thread, but I've been editing the docs with BlueFish instead of a "WYSIWYG." I don't mind hand-writing it, and the built-in CSS and HTML guides are a huge help.

I'm going to use the above for the overview and guides and I found a DOxygen Eclipse plug-in for the API documentation. I'd never used DOxygen for C documents, but it's a whole lot less painful than using it for C++!

The project should be up and running with docs in no time. I just need a slow weekend where I can sit down and hammer out at least 2 of the 4 guides I need to write. Here's a link for now:
Resourcerver

Thanks!
ta0kira

Sorry to seem like a Johnny-come-lately, but I just stumbled over this.

Glad you found a way to use HTML -- I detest PDF for documentation. My biggest bitch is that I can't zoom the display to a size that is good for my old eyes & have it stay w/in the edges of my screen. Konqueror, my default browser, can usually do this; & Opera is superb at dealing w/ the most recalcitrant cases.

BTW, please try to provide a single page ver., rather than a multi-page only -- it really facilitates searching the whole document.