views:

763

answers:

6

I am sure they use something really fancy to create their documentations and guides. Everything is so streamlined and equal, and they always have a HTML and a PDF version. Now we make a big framework and want to provide a good documentation that's set up the way Apple does it. Online in HTML format and offline in PDF.

Any idea how the Apple folks did it? What tools they use?

A: 

I think they created a lot of technical documentation with Adobe Framemaker.
Even for some of their newer products (iPhone, ...).

This is remarkable because there is no Mac OS X port of Framemaker.
I wonder what they use nowadays. The last Mac OS version that is capable of running System 9 software is Mac OS 10.4.11 in classic mode.

weichsel
Not to mention classic mode was removed from Intel Macs - surprised me when I first tried using one of my old apps on my Mac Mini (no, I hadn't upgraded in a long time).
David Thornley
+2  A: 

I don't know about what Apple uses, but there were two well-answered questions in the past few weeks about generating documentation both on the end-user and the developer end.

Some of them come certainly close to what Apple produces in terms of neatness and good looks, however you may need a skilled print designer to add that certain zazz. Don't forget that Apple's products are the product of painstaking, high-quality detailed design work and just using the tools they used does not automatically guarantee the same results.

Pekka
+3  A: 

I'm pretty sure they use something called XEP by a company called RenderX. If you look at the PDF for The Objective-C Programming Language, XEP is listed as the PDF generator.

If I'm right, Apple creates all their documentation in an XML file (seems plausible enough!). Then you run that file through XEP and it outputs it with proper formatting, links, etc.

Chris Long
A: 

Maybe you want to use some sort of automated code documentation. Have a look at Apples Headerdoc. My company is currently working on a framework and we use Doxygen (doxygen.org). Using such tools, you have great freedom to create several formats like HTML or PDF from a single source, plus you have your code documentation implicitly done during development.

Hutaffe
+7  A: 

I'm not sure what tools Apple uses internally. Since I've had the exact same need, I'll share what I learned and what I ended up doing.

Two of my open source projects required "very high quality" documentation which ideally would be indistinguishable from the documentation provided by Apple. The two projects are:

RegexKit was the first project. I looked around for something, anything, to help with documentation. The only two tools that seemed to be up to the challenge were Doxygen and, suprsingly, a tool that ships with Xcode: HeaderDoc. Keep in mind this was a few years ago, so things have probably changed a bit.

Existing Tools

Doxygen is used by a lot of projects, but I've never liked the 'style' of what it generates. Not to mention it was nothing like what Apples documentation was like, and from what I could tell, getting it to generate what I really wanted just wasn't practical.

Initially, HeaderDoc looked promising. In fact, several of the frameworks header files include HeaderDoc markup, for example:

/System/Library/Frameworks/CoreFoundation.framework/Headers/CFArray.h

It quickly became apparent that HeaderDoc just wasn't going to cut it. It was slow, very slow, and its HTML output was essentially 'set in stone'- there was no template system, for example. Whatever came out the back end is what you were stuck with, save for some trivial changes you could do with CSS style sheets.

The RegexKit Solution

So, what to do? Since I had already marked up some of the headers using HeaderDoc markup, I decided to roll my own. It all part of the distribution if you want to take a look at it. It definitely shows its pedigree though: started off as a quick hack that just kept on growing and growing. Not pretty, nor meant to be understood, let alone modified, or even used by anyone else. It's essentially a complete documentation system: it parses header files, extracts not just the HeaderDoc markup, but the actual source code that's being marked up as well. All that raw info is dumped in to a sqlite database, and then a script generates the final HTML output. Because everything is parsed first, inter-header references (for classes, types, etc) are no problem. It also allows the Table of Contents to be generated automatically.

With quite a bit of effort in tweaking single pixel distances via a CSS style sheet, it is (or at least, was, at the time) a nearly pixel-perfect emulation of the HTML documentation supplied by Apple. Apples documentation style changed slightly for iPhone / 10.6, but it's still very close.

Not only is it nearly identical to the HTML documentation, a lot of effort went in to a special "printer media" style sheet so that if you print the documentation from a browser, particularly Safari, it looks nearly identical to Apples PDF documentation... especially if you have the right fonts- Palatino and Letter Gothic. Since Safari is obviously tuned for screen output, not printer output, it will do page breaks at inconvenient places... but it's definitely passable. Zero changes to the HTML, it's all done automagically with a CSS style sheet change.

When I started, Mac OS X 10.5 had not yet been released. With 10.5 came DocSet, which allows for documentation to be tightly integrated in to the Xcode editor. Since everything was stuffed in to an sqlite database, it only took a few days to generate the required XML files needed by the DocSet tools. Even though it was a lot of extra work to build the documentation system, being able to integrate all the documentation directly in to Xcode with just a few days of effort made it worth while.

The RegexKitLite Solution

RegexKitLite came later, and as you can guess from the 'Lite', it's meant to be smaller. I wanted just a single HTML file for everything. I started off with the templates and CSS stylesheet work done for RegexKit and built the HTML file "by hand", nothing automated to it. Even the XML files needed for DocSet were seeded with stripped down versions from RegexKit and then edited by hand.

If you can't find a solution and need to roll your own, I'd strongly recommend you grab a copy of the RegexKitLite HTML documentation and use it as a boiler plate. The documentation is covered by the same BSD license, but you're free to gut the contents and use the remaining skeleton as a template without attribution.

Since RegexKitLite is the "newer" of the two, it's received the most love. I know its CSS style sheet is much better and has a lot of improvements over what I started with from RegexKit. Also, you can just rip out all of the JavaScript <script> stuff since its sole purpose is to allow you to select/highlight a regex in the document and then do some automagic fancy regex -> NSString escaping when you do a copy / Command-C in Safari.

The Ideal Solution... or what I want for Christmas.

My ideal solution would be some kind of easy to use markup. In the end, I didn't really like the HeaderDoc markup style. Definitely needs to be flexible and user extendable, and template oriented. HTML, and especially XML, is way to verbose in my opinion. I think I'd prefer something more like Markdown or reStructuredText, but obviously tweaked for the task at hand. In particular, it would be nice to have short-hand markup for referencing stuff like other classes, types, etc, and the template/backend automagically rewrites it to the targeted output format, say HTML, and automagically hyperlinks a reference for you as needed.

For high quality printed output though, you're almost certainly going to end up using TeX, LaTeX, or one of their derivatives. I haven't had to use *TeX extensively yet, but it's purpose built for book / printed media publishing. It's also fairly trivial to build very high quality 'diagrams' with just a few dozen lines of text. For HTML, you're pretty much stuck with creating a bitmap image using another tool chain (photoshop? visio? etc).

I've also though about just biting the bullet and moving completely over to a *TeX tool chain, and generate HTML from the .tex sources. Every time I've tried, though, I've just been overwhelmed. It's an incredibly powerful tool, and .tex source / markup isn't that bad... but learning enough to tweak things to get the exact style of output I want is... well, lets put it this way. *TeX was created by Donald Knuth, of The Art of Computer Programming fame because when he went to write his books, which required very high quality typesetting of mathematical formulas, he was dissatisfied with the existing solutions. So he spent a few years and wrote his own. He was at the bleeding edge of modern computer typesetting and typography, and out-right created chunks of it, in the process.

johne
+2  A: 

Not a direct answer to your question since I'm pretty sure this is not what Apple uses, but AppleDoc might be worth looking into.

In its developer's words: "The idea for such a utility came from a lack of good document generator for Objective C that generated nice looking documentation." From the example documentation that's provided on the site it's clear he's looking to emulate Apple's layout. Haven't had a chance yet to try it myself though.

Rinzwind