Take the 2-minute tour ×
User Experience Stack Exchange is a question and answer site for user experience researchers and experts. It's 100% free, no registration required.

What's the industry-standard way to document a design pattern?

I have seen websites like ui-patterns.com and patternry.com that host and share design patterns, but when creating an reusing a design pattern, is there a standardized way to document that pattern other than just screenshots and descriptions?

For example, this "Slideshow Pattern" on UI-Patterns has a screenshot and description below, but is that "how the pro's do it"?

Shouldn't there be some sort of diagram with these screenshots and descriptions?


Design Patterns

share|improve this question
1  
Are you asking about how to create a design document –  Mervin Johnsingh Mar 17 '12 at 7:16
    
@MFrank2012 - I think that is a relevant document (I hadn't heard of an software design document (SDD) until you shared), but I don't necessarily mean project-specific. I guess I mean more of a standard for documenting a specific design pattern. –  DesignerGuy Mar 17 '12 at 7:18
1  
Well we call it design specifications document..The software design document details the technical implementation details –  Mervin Johnsingh Mar 17 '12 at 7:20
    
For what purpose? Documenting patterns in general is very different from documenting patterns used in a particular project. –  dnbrv Mar 17 '12 at 7:42
1  
In this industry there are no true industry-standards for anything (that I know of). There are often more or less similar ways of doing stuff, but nothing to the level of a standardized document. –  Vitaly Mijiritsky Mar 17 '12 at 7:44
show 2 more comments

2 Answers

I'm told there isn't really an "official" way to document a design pattern, but this seems to be an effective format:


  • Title of Pattern
  • Other names for the pattern
  • Screenshot
  • Diagram(s)
  • Context
    • What problem(s) it solves
    • When to use it
    • When not to use it
  • How to use it
  • Additional Resources
    • Links
    • Examples
    • Code Snippets

The only thing I really added that I specifically haven't see "out there" is diagrams. I feel as though a lot of descriptions of design patterns are lacking something to show the anatomy and/or interaction of the pattern.

share|improve this answer
add comment

We kind of follow this structure ( I admit its an adaptation of the process of documenting reusable components in software design)

Pattern Name and Classification - A short, meaningful name for the pattern, The names are chosen with regards to the use and application of the pattern and the combination of predefined terms. For example,if the design pattern is an adaptation of a carousal, we might name it as a single left scroller carousal

Screenshots - Mostly high fidelity ones but also low fidelity ones depending on the level of definition of how we feel the pattern would be

Problem statement- A general description of the problem and constraints which the design pattern aims to solve. We normally do this by defining a use case scenario where such a need is there and how users can use the pattern to handle it. The problem statement should provide guidance to assist others in recognizing situations where the pattern can be applied.

Technical design specifications - This is the more technical aspect of it but here we normally highlight the details such as how it was implemented (e.g. Jquery,ASP.NET,web parts) and how it could be integrated into the system and what are the related dependencies (like is it pulling information from somewhere or does it need a certain Jquery file etc.)

Consequences- This is usually an discussion of the results and tradeoffs of applying the pattern. The alternate variations and options are also highlighted

Known Uses-Examples of the pattern in real systems and scenarios where it could be adapted.

If the design pattern is pretty large or has a number of "moving parts", we also create a table which highlights the functionality of each of those "moving parts". The table format is something like this :

enter image description here

A Google search brought up this layout which in my opinion is awesome :

  • Name
  • Screenshot(s)/working solution
  • What Problem Does This Solve?
  • When to Use This Pattern
  • Why Use This Pattern?
  • Special Cases
  • Pattern library

Other examples of layouts : Carousel UI Pattern

share|improve this answer
    
Great answer. I can see the software roots :-P –  DesignerGuy Mar 17 '12 at 8:02
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.