Good question. In my experience, I’ve not come across a pre-fab application for documenting patterns, components, or other libraries of reusable design assets that have the types of attributes (e.g., Use When) and other specific features. Instead, I’ve seen that teams have gone one of four routes to publish library documentation:

1. Home-grown systems: This is expensive and time-consuming, but ultimately the most advanced and tailored solution for an organization. Yahoo has written (on boxesandarrows.com) and subsequently spoken extensively about the challenges and roadmap they’ve traversed. Sun Microsystems has also use a custom website as the cornerstone of their efforts; lucky for us, they expose it to the community too at sun.com/webdesign/.

2. Collaboration tools: One team effectively used Jive Software’s Clearspace tool that includes a well suited three-prong feature set: wiki (articles per pattern & component, including editing permissions for team & individual, commenting and ratings), discussion boards (new requests, general discussions), and blog (publish ongoing notifications and articles about the overall library).

3. Basic tools: Other teams have set up a wiki or tried to transform a basic collaborative tool to publish patterns. This may be a good short term fix, but isn’t really a tenable long term solution unless you can really start to customize it.

4. Documents: For better or worse, some teams don’t have access to web-based solutions for publishing a library, and this really hamstrings their efforts. That said, they’ve gone to great lengths to compose documents (like a “Component Guide”, “User Experience Guide”, or “Pattern Library”) that become a versioned document managed over time. Additionally, with a modular documentation system, they can architect their guides in such a way that pages can be linked to project-specific documents as appendices or even key pages to scale changes or overlay annotations.

Hope this helps!

Nathan

I’m not aware of any purchasable pattern library systems. I’ll ask Nathan Curtis to see if he knows.

Jared

* Name

* Primary example — a screenshot or photo which captures the pattern perfectly

* What — a soundbite description; if I can’t capture it in one or two sentences, is it a pattern worth putting into the book?

* Use When — the context of use

* Why — an explanation of the design principles underlying the pattern

* How — advice, suggestions, pitfalls, alternatives, and related patterns

* Examples — an assortment of diverse examples that illustrate the range of the pattern; critical for visual thinkers

This simplified structure went over better with the intended audience than the more Alexandrian structure I had used in a previous iteration. A very few people have asked for additional sections — “Related Patterns” being one — but the information’s already there anyway, usually under “How.”

And yet I don’t think your long list of section names is wrong. Why? Context of use, of course!

I wrote these patterns as a teaching tool and a brainstorming aid. They were not a collective, collaborative effort; they do not represent the history of a single organization’s design work. If they did, then I’d agree that sections such as Specifications, History, Code, and especially Usability Results would be very important indeed.

Still, a long document can be scary-looking. If you want your patterns to be read by as many people as possible, I think you shouldn’t overwhelm them with five pages’ worth of stuff. Put the sections most important for hurried readers up front; hide the rest behind another link or something. As described in the “Extras On Demand” pattern, of course.