Open Radar

 
Summary: The documentation viewer no longer shows a Table of Contents

Steps to Reproduce:

1) Open the "Apple Human Interface Guidelines"
2) Look for a Table of Contents.
3) Open the dropdown arrows in the sidebar and look for "Managing Complexity in Your Software"
4) Use the Jump Bar menus to find "Managing Complexity in Your Software"

Expected Results:

In step 2, you should see a Table of Contents for this chapter-based documentation.

In step 3, you should see the section listed in the sidebar.

In step 4, you should be able to see other chapters.

Actual Results:

In step 2, you don't see a Table of Contents.

In step 3, you don't see the section listed in the sidebar.

In step 4, you can't see the other chapters because they are covered by other menus.

Regression:

This is a regression from Xcode 3.

Notes:

The chapter-based documents are the crown jewels of Apple's developer documentation. Titles like The Objective-C Programming Language, iPhone Human Interface Guidelines, and the Cocoa Fundamentals Guide are essential reading for all developers, both beginner and advanced. As I began learning about Xcode 4, of course I turned to the excellent User Guide.

These guides typically span many chapters when sections that cover a wide range of topics. And this is how you navigate through those chapters:

http://furbo.org/wp-content/uploads/2011/03/Unmanaged_complexity.png

The pity here is that someone has forgotten that a Table of Contents tells a much more important story than the individual chapters. A roadmap lets you visit the destinations efficiently.

To get an idea of how painful this is, try finding the recommended Singleton implementation in the Cocoa Fundamentals Guide using the Jump Bar.

Of course the documentation viewer has a search function, but even that's a bit laborious because you have to click on a lot of disclosure triangles to find the right item in the results. Why aren't the relevant results opened automatically? (And, yes, option clicking the disclosure triangle can be used to achieve this goal, but the question still remains: why isn't this the default action?)

The root of the problem here and with the method names in the class documentation, is that a deep hierarchy is too hard to navigate. Present the information in a single list and it becomes much more useful. Imagine how bad the code editor navigation would be if it presented a hierarchy based upon classes, properties and methods. It's flattened into a single menu for a reason: and those same reasons exist in the documentation viewer.

The Jump Bar is a great addition to Xcode, but it's true power lies in having a predictable end point. With code, that end point is a function, property or method. With documentation, that end point is elusive: it varies depending both with the type and the structure of the documentation you're viewing. And that's a real problem when you're looking for something.

More information (including screenshots) at: http://furbo.org/?p=334