We – have – A – P – I!!

Thanks to the good work of Ajdin, we now have an HTML API that serves Patterns and Cases in XML, PLML, RSS or CSV. I’ve also added a generic API, which allows you to browse all object in the system in XML/HTML.

The intention here is to allow other design pattern / learning design repositories to interface with our system programmaticaly with as little effort as possible. Other systems could list our objects, include them in searches, support easy linking, or offer an alternative interface (read only, for now).

More should be coming, so you might want to watch http://patternlanguagenetwork.myxwiki.org/xwiki/bin/view/api.

But there’s also a caveat: we’re still in the experimental / conceptual phase. These APIs work, but they are also subject to change. We give no guarentees of backward compatibility. So if you use them, make sure you wrap them with an abstraction layer on your end.

Finalising a pattern structure

We have had many discussions about the structure we need for a pattern and the template on the wiki has been updated to reflect some of these. However I don’t think we have agreed a structure that we can work with from now on. My own view is that the current structure is incomplete and does not give enough support to people moving from protopatterns to patterns. It would also be useful to use a structure which is compatible with other collections to allow more seamless reuse of the patterns of others.

I proposed some changes some time ago based on the PLML pattern elements – the resulting discussion was then summarised by Jim. I’d like to take that further now and propose an actual specification for the structure. I believe our template should include the following elements (comments in parentheses):

• Name (short, memorable but not so gimicky as to be meaningless to anyone outside the initial discussion)
• Illustration (a picture showing an instantiation of the pattern in real life – so a photo, screenshot, video – rather than a diagrammatic representation)
• Problem (the design challenge the pattern will address)
• Context (described by PLML as “applicability” – what kind of situation does this pattern apply to?)
• Solution (the instruction that resolves or addresses the challenge expressed in the problem)
• Diagram (a schematic or diagramatic representation that captures the essence of what the pattern is about – could be a sketch or a more formal representation)
• Evidence – to include 3 sections (either formally or indicated in the section “advice”):

1. Examples (cases where this pattern is seen)
2. Rationale (principles, evidence from literature etc to back up pattern
3. Links and references (supporting the above)

• Related patterns (patterns within the language – or another) that this one extends, is part of, contains, is the same as etc)
• Confidence (how sure are we this is a pattern – may be related to the level of evidence, the rule of three etc. – suggest a three level “star” rating).
• Author
• Licensing (as now)

I think this is in keeping with our previous discussions but that of course is open to disagreement! Some of these may end up being collapsed into one field; others may be optional. However, given the difficulties users have had in knowing how to move from case to pattern, overspecifying the structure seems appropriate to begin with.

Our plan is to use this format for the ALiC workshop this week and work on scaffolding questions and activities to help our participants map their cases onto it. We’ll keep you posted.

Thinking about structures

A sub-group of the Planet team had a profitable time this morning meeting with Jill Jameson our very encouraging critical friend and discussing the progress, successes and challenges faced by the project. After Jill left to see ARGOSI, John, Isobel and I mused about some of those challenges and how we might address them. One that we need to finalise quickly is how we can best structure individual patterns to make them most accessible both to those involved in creating patterns through our workshops, and those who will hopefully come along later and want to make use of them in guiding their teaching practice choices. Planet wiki currently uses a form inherited from the Learning Patterns project which includes the pattern name, aim, context, solution, related patterns, examples (case studies/scenarios), note, links and references and legal rights. However we have had some debate as to whether this captures all that we need and whether the sections are clear enough.

In 2004 I was involved in organising a workshop at the CHI conference where this issue was the primary focus. One of the outputs of that workshop was PLML – a pattern language markup language – complete with DTD, specifying the elements that might be included in a pattern. The basic pattern element looks like this (full details and spec are available from the link above):

<!ELEMENT pattern (name?, alias*, illustration?, problem?, context?, forces?, solution?, synopsis?, diagram?, evidence?, confidence?, literature?, implementation?, related-patterns?, pattern-link*, management?)>

It is interesting to compare this to our structure, noting that only the unique identifier is essential in PLML. We have a name – though it could be more obvious on the pattern page itself. Our “problem” is called “aim” (I think I prefer problem – suggests the problem solution pairing that we are looking for). We have context, solution, evidence (our examples – though we could also have a rationale element), literature (our notes), and related patterns. Our legal element might be part of the management section – which could also include version and authorship information which is effectively managed by the wiki itself. So what is left? Looking at the elements that we don’t have, three stand out as being particularly useful: illustration, diagram and confidence.

It has been said that a pattern is not a pattern if it cannot be drawn. That may be an exaggeration but the concept of illustration of patterns is one which is critical I think to their accessibility. It really is a case of a picture being worth a thousand words. In the case of learning patterns the illustration might be a photograph or an artefact or a diagram or even a video – but there should be some visual way of representing the essence of the pattern that lets others have that “a-ha” moment. Perhaps here we need to talk to John Sandars and the Reflect 2 team about their activities..? Not sure if we need both illustration and diagram (they do serve different purposes so maybe we do) but certainly illustration.

The other area is confidence. At the moment our patterns are categorised by their level of development – seed, alpha, beta. But this is slightly different from the idea of confidence – it would be possible to have a well developed pattern in which you had limited confidence, perhaps because there was not much substantiated evidence to support it. Confidence is how sure we are that this really is a pattern. Alexander used a star system which was elegant and informative – you can see at a glance which patterns are the strongest in his language.

So from this I propose that we consider some adaptations to our current form:

• Change “aim” to “problem”
• Add “illustration”
• Add “confidence”
• Make “examples” a subsection of “evidence” and add another subsection “rationale”
• Make the name clearer and maybe allow aliases.

Thoughts anyone?