Requirements Inspiration From a Surprising Source
Last year, while studying for the certification exam, I started to see everything in CBAP terms. Cookbook? Requirements document. IKEA assembly instructions?
Functional requirements with process diagrams and mock-ups. 10 Commandments? High level requirements. And so on.
In my spare time, when I wasn’t trying to learn the 34 commonly used requirements techniques or all the task inputs and outputs, I would relax by knitting. I am a serious knitter who takes classes to improve my skills when time permits. A few years ago, attended a 2-day workshop titled Japanese Pattern Boot Camp (really!) to learn how to read those intricate and innovative Japanese knitting patterns that are rarely translated into English.
I wasn’t sure how the workshop could teach me how to read a pattern written in the logographic system of kanji, but I was utterly delighted to learn that Japanese patterns are among the most ingenious and concisely written requirements documents imaginable.
JAPANESE PATTERNS AS MODEL REQUIREMENTS DOCUMENTS
Here is a sample Japanese sweater pattern from Pierrot Yarns which has kindly permitted the use of their pattern in this article.
Since most of you are most likely neither knitters nor literate in Japanese, let me point out the many admirable characteristics of this requirements document.
HIGHLY VISUAL. As you can see, a Japanese pattern is short on words but long on graphics, unlike English language patterns which tend to be just the opposite. This single page contains the entire pattern. In contrast, this pattern could easily take 3 or even more pages if written in the older style of , English pattern writing.
{module ad 300×100 Large mobile}
So, what do these graphics represent? Anyone who has ever made a garment would recognize that the top 3 diagrams represent the back of the sweater, 1 side of each front, and a sleeve. The bottom 2 charts show the pattern stitches used when actually knitting the garment.
UNIVERSAL MODELING LANGUAGE. How in the world is anyone to know what the squiggles in those charts mean? There is a standard set of symbols (a knitters alphabet, if you will) that are universally understood. Furthermore, there is a common understanding of how to follow a chart. While in English, we read from left to right and then top to bottom, knitting charts are meant to be read bottom to top and tracing from right to left and then back again. That may seem bizarre to you, but this is the standard way that knitters read charts the world over.
Related Article: A Process Approach to Requirements Gathering
IMMEDIATE TRACEABILITY. On the diagrams of the pattern pieces (top row), you’ll see that there are (a) numerical notations, (b) arrows, (c) the letters “A” and “B” and (d) vertical and horizontal bars with lines through them. The arrows indicate whether the section is to be knitted from the top down (↓) or the bottom up (↑). The “A” indicates that the stitches in the chart labelled A (i.e., the one on the left) should be used in that section. The sections with a “B” in them should be knitted with chart B.
The bars at the top and side show the finished measurements in centimeters of each specific section of the garment. The beauty is that the since the requirements are noted next to the relevant area, there’s immediate traceability between the requirement and the relevant portion of the diagram. No need for a traceability matrix!
CONSISTENT USE OF STANDARD NOMENCLATURE. It’s possible to figure almost everything out without tackling the Japanese characters, but they’re not completely avoidable. Fortunately, there is a very well-defined, limited vocabulary of knitting terms that are used consistently across all patterns. Using the single page of terms in this Japanese-English Knitting Dictionary, one can decipher just about everything on a pattern.
STANDARD COMPONENTS OF REQUIREMENTS. Even using the dictionary linked above, it would still require an enormous effort to search through the page for every character on the pattern. Happily, that is not necessary since there are standard components of information presented in a standardized layout. At the beginning of every pattern, there’s always
- a list of required materials (i.e., inputs): yarn amounts and fiber, needles of a specific size, possibly buttons or trims
- the gauge of the stitches. Gauge is the number of stitches and rows per inch you should achieve
- measurements of the finished garment (key indices, so to speak): chest circumference, sleeve length, body length, etc.
Knowing what to look for limits the vocabulary to be searched, and just helps one get oriented
“JUST ENOUGH” DETAIL. Japanese patterns do not provide any more detail than is absolutely necessary, and assume you have a certain base of knowledge with which you can fill in the blanks. All that is provided are the key requirements needed to produce the final product.
KEY TAKEAWAYS
Probably only a few of you are knitters who will be inspired to start using Japanese patterns. However, I think that there are several principles that can adapted to improve our requirements documents.
- Use visual models to facilitate understanding . Process flows, context diagrams, data diagrams, and other models can effectively and concisely convey requirements more succinctly than pages of text. This is particularly valuable when working with team members who are not native English speakers. I highly recommend Visual Models for Software Requirements by Joy Beatty and Anthony Chen to learn about different models, how to construct them and where each type of model is most appropriate.
- Define your terminology and use it consistently. Do not alternatively refer to a business unit as a “group”, a “team” and a “department.” Those terms may be synonyms to you, but they may mean very different things to your audience. Ideally, maintain a glossary used by different areas, so everyone starts adopting the same nomenclature.
- If possible, annotate your diagrams with helpful information or links to the relevant enumerated requirements elsewhere in your document.
- Consistently use a standardized format. Many organizations already have a standard template, and that’s because it enables readers to find readily what they need to know
- Provide “just enough” requirements at the appropriate level of detail for your audience. You may have to go through several iterations to ensure that everyone has the information they need.
REFERENCES:
1. “98-3 Lace Cardigan,” © Pierrot Yarns (Gosyo Co., Ltd), accessed 23 March 2016, http://www.gosyo.co.jp/img/acrobat/98ss/3.pdf.
2. “Japanese-English Knitting Dictionary”, accessed 23 March 2016, http://www.tata-tatao.to/knit/japanese/e-JapaneseEnglish.html
3. Joy Beatty and Anthony Chen, Visual Models for Software Requirements (Redmond: Microsoft Press, 2012).