I really like my system!
Although it is NOT single-code-based, I find it very effective and best of all makes everything look like I want it to. This is something all the automated solutions downplay. Documentation should look good to impress your customers/clients. I am not convinced any of these automated solutions, even the expensive ones, have the intelligence (if it’s even possible) to make a decent-looking PDF document based on what has to be HTML for the other Help methods.
I start with a HTML-linked file set. On Windows I use the standard old HTML Workshop from Microsoft to make the CHM Help File (standard). For Mac I simply move it into the app bundle and HelpViewer displays it and it looks great. Also, in my apps, I link to my company’s web site which has this same HTML code-base but it may be more updated than what their current HelpFile/HelpViewer is.
So far so good, everything is platform-specific and industry-standard so no one should be surprised.
For the PDF I use Adobe’s inDesign, the best IMHO layout program around. I’ve used Pagemaker since the 1980’s so it’s real easy for me to use. Like I said, I have to transfer by hand everything from the HTML, but I make sure initially I do the PDF LAST, when I’m very confident in the HTML. That way I’m not going back and forth on the initial pass.
Layout things on a page is so much different that laying it out on HTML, you want things to wrap differently around graphics and you want page breaks to be natural and not broken. HTML could care less about page breaks. And I want my PDF’s to look great, so I do this extra work, but it’s worth it.
As far as maintenance goes, I have to ALWAYS make sure I synchronize the PDF to the HTML. That takes discipline, but isn’t that what programmers are supposed to have? So I always - no matter what - open up Dreamweaver and inDesign when I am editing the docs. I do the HTML first and make sure I copy-paste over to inDesign afterwards. No quickie too-fast junk. With inDesign I can always keep in mind how I want larger or added areas to naturally flow, and when to page break appropriately so it’s natural to the reader.
BTW, the HTML and the PDF do share graphic files, so any changes in those automatically update the PDF. So there is some sharing, although it’s important for me to check the PDF so a graphic replacement that is a bigger size doesn’t look screwy or throw off the layout flow.
I made this sound complicated, but it’s not. Once you get in the flow it’s very natrual and easy. And VERY IMPORTANTLY, one of the great things documentation does for the programmer is clears your mind and forces you to do things in your program THE CLIENTS WAY, not YOUR WAY. The maxim: if you can’t explain it, you shouldn’t program it. You said you don’t like doc’ing - I get that, but really it’s so helpful for your work.
I’ve been doing this for 5 years now and I’m extremely pleased on how well by docs LOOK, and how well they synchronize. MAYBE I’m clueless about how good some of these automated programs are, but first I’m not paying the money, and second I’m absolutely convinced that good PDF print layout is ONLY accomplished by hand. Quality is important to me, I may not always succeed, but I’ll always hold the highest standards in play.
