A Suggestion for design pattern format in the DPL

[erin yu]

Hi, I just realized my email below didn't go through to the list.
Thanks Allison for letting me know.

Here's my original email.

Jon and I have recently worked on the Inline Edit and Pager design
patterns. Being new to authoring design patterns, we thought about
what topics/sections should be included in a design pattern, what
each of these should talk about, what other pattern libraries have,
etc.

Based on our discussion, we came up with a suggestion for a slightly
modified format for our design patterns and would like your feedback.

No big changes have been made - we just wanted to reduce
redundancies and clarify exactly what should be discussed in each
section so it's easier for the authors and readers.


[Title]
The title of the pattern and optionally the alternative names of the
pattern (what the other pattern libraries call it)

Problem
"What the problem is this pattern trying to solve?"

Use When
"When you encounter these situations, use the pattern."
Describe the characteristics of the situations then the pattern
should be used to help the integrator determine whether they should
use the pattern

Solution
"So when you have the situation above, here's what you do."
Briefly describe the solution along with some screenshots, so people
can see what you're talking about at a glance.

How
Explain the solution in detail. What interactions should happen. How
the system provides/responds to the user's needs/actions.

Rationale
This section is currently called "Why" and placed right after the
Use When section. Because of its placement, it wasn't immediately
clear as to what it was about. Also I found there are a bit of
redundancy between the Why and Use When sections.
Instead, it would make more sense to explain the solution first,
then explain why the solution is the way it is, provide reasons
behind the design decisions made, provide Rationale! ... and hence
call the section Rationale.

Accessibility
Recommendations on keyboard interaction, text to be read out by
screen readers, etc.

Examples
Links to other web pages where a similar design is used.

Related Fluid Components
Link to the overview page of the related components

-Erin
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://fluidproject.org/pipermail/fluid-talk/attachments/20080704/62174ad6/attachment.html>