Documentation
Posted February 14th, 2004 @ 07:40pm by Erik J. Barzeski
As PulpFiction's deadline nears (we're shooting for March 1, which of course means sometime in August), we're weighing the two primary forms of documentation: a PDF document* or a series of HTML documents.
PDFs are great in 10.3. Preview allows people to load PDFs quickly and perform live searches. PDF documnts can be copied or printed without incident. PDFs can also be deleted easily and are often a bit bloated.
HTML documentation ties in easily with Apple's help system, but fails where when the "P" in PDF is important. It is searchable as well, but only through Help Viewer. Recent advances in Help Viewer's renderer have made styling HTML-based help possible.
As PulpFiction is a 10.3-or-later application, we can rely on Help Viewer not - how should I put this - sucking ass as it did in 10.0-10.2. I think that we'll go with HTML documentation, but I'll listen to any feedback before we decide for sure.
What's your opinion of documentation styles? What application has the best?
* Previous PDF documents for FSS products were created in AppleWorks and printed to PDF. We realize that this is hardly optimal.
Donate Life
Posted 14 Feb 2004 at 8:14pm #
Do both.
Keep the HTML documentation for Help, but keep a PDF along with the program.
Posted 14 Feb 2004 at 8:24pm #
It could be that hard to do both but if you have to go with one, go with HTML. that way you have the search in help viewer and you can post the files to your website so people can browse the help before they download and under the help menu add a item like "Dynamic Help Files" with take you to a php powered FAQ and updated copy of the help files.
I assume it is an internet application so why not have the help on the internet and a copy on their computer just for backup?
Posted 14 Feb 2004 at 8:25pm #
Sorry that should read, "It couldn't be that hard to do both..."
Posted 14 Feb 2004 at 8:29pm #
We won't do both. PHP isn't necessary - Help Viewer automatically downloads updated documentation from online if it finds new stuff. I don't know if we'll do that, though. I haven't yet begun to look into what's involved with that.
Posted 14 Feb 2004 at 9:07pm #
Help Viewer does download new documentation? Wow. I didn't know that but then again the only times I have opened help viewer was once in 10.0 (way too slow, felt like a google search was faster) and when I accidently hit help instead of delete. I haven't tried the one in panther yet... I guess I will open it now.
Posted 14 Feb 2004 at 9:45pm #
I would vote for HTML. But that's just me. I hate PDF documentation that I have to look through. Of course, if you do everything in HTML, you can always "print" it to PDF..but eh. As far as updating, the application can even do that when you download the new version of the app. Not super important. Really...the best way is HTML (IMHO).
/vinay
Posted 14 Feb 2004 at 10:19pm #
I really have to vote for PDF. I just recently got Final Cut Pro and all of its manuals are in PDF. Now that Preview is so frickin' fast in 10.3, I prefer that format to anything else, especially the oh-so-cranky Help Viewer. Just my two cents...nate
Posted 14 Feb 2004 at 10:35pm #
I really dislike HTML that's broken down *too* much across pages, like the developer docs. It becomes a pain to print, and there's something disappointing about clicking to the next section and finding only a short paragraph.
Often, I'd rather just have a long single file in which I can use a Find panel to jump around. I preferred NeXT's rtf class docs over the HTML class doc + umpteen Task & Concept pages approach which Apple has moved to, in part by pulling stuff out of the class doc reference pages.
I loathe HelpViewer, though in part that's because Apple's docs are so unsatisfying - so many things aren't in there, or are mentioned but not explained. There's no detail.
Posted 15 Feb 2004 at 12:14pm #
The documentation system I use is LaTeX. I like it because you can output PDF, HTML, XML, PS, etc (one LaTeX document to rule them all), you can use a great freeware editing system (TeXShop), and it plays nicely with source control (READ: diffable/mergeable).
It's cons: importing pictures is a little screwy, and you'll need to include them as binary in your source control tree. Native graphics are vector based, but there's not good native editor in OSX (I hate xfig).
Good luck
Posted 15 Feb 2004 at 12:29pm #
I've used LaTeX and pretty much hate how much work is required to do simple things like scale an image, position it properly, get colors going, etc.
Outputting PS (who uses that as documentation?) and PDF - fine. Outputting HTML/XML take more work - a lot more - and so on.
LaTeX wasn't included in my list of possibilities because, given its use here, it sucks. It's good at other things: not so good at creating awesome manuals.
Posted 15 Feb 2004 at 10:16pm #
LaTeX's HTML export sucks, the format just wasn't designed for a format like this (this is just as bad as converting a web page to PDF).
Posted 15 Feb 2004 at 10:20pm #
I have no interest in printing the documentation -- this is the 21st century and I'll read it onscreen thank you. So just use Help Viewer. It's fast enough and the searching is good.
Posted 16 Feb 2004 at 8:18pm #
Panther's Help Viewer is pretty reasonable, now that it uses WebKit. (Although it still has annoying bugs, at least it runs at a usable speed.) I'd use it for anything which is Panther-only.
Posted 18 Feb 2004 at 6:26pm #
Is anyone using DocBook to write their help file? It's an XML standard, same basic principle as LaTex except it's intended for writing documentation instead of generic documents.
I've found a very good editor for DocBook documents:
http://www.xmlmind.com/xmleditor/
It seems to generate great PDF files, but I'm not sure how easy it will be to make it export HTML that will be good for the applehelp viewer.
Jesse