7 years, 2 months ago


In addition to story narratvies, I’m planning to use ‘pattern’ format for describing the Change Design tools: Here’s an example that describes the Business Service Specification tool (BSS). I would also then go on to describe how it’s been used in two or more situations. I will also include templates and other materials for anyone wanting to try the tool.


Services Documentation

WHAT before HOW fact-sheets

Headline: A shared, service-focused, language for everyone

Kicker: Lack of common understanding of management tiers creates funding barriers and increases the risk solutions of not delivering required business outcomes.

Everyone, from the C-Suite down, benefits from a common understanding of the services being developed or procured. This requires a shared language that is non-technical, and focus on WHAT the service does rather than HOW it’s implemented. Traditional requirements documents, process models, and architectural abstractions are too unwieldy and often either too fluffy or too technical to provide the needed clarity.


  • Developers want to focus on producing working code rather than documentation.
  • The C-Suite don’t care (or shouldn’t care!) about how the software is developed, but do want input into the metrics that measure the performance of the Services implemented, and the business outcomes delivered.
  • Dispersed teams would benefit from a simple, low-friction, way of describing the services they are working on in a common lingua franca (this is particularly true of pan-national teams).

  • Agile practices can been extremely light on WHAT level documentation.
  • Traditional Business Analysis and Architecture documents are not fit-for-purpose (arcane, unwieldy and require specialist skills to develop and interpret.


  • Iteratively develop a small set of ‘Service Fact-Sheets’ that describe the WHAT aspects of a S/W component or external Service consumed.
  • Each Fact-Sheet set follows a standard structure and semantics.
  • A Fact-Sheet set is no more than four A4 sheets long.
  • The minimum data is less than ½ page long.
  • (Assumption) Some of the data can be collected Passively from tools and augmented with further details provided by a Business Analyst or similar responsible party.

Resulting Context
All decision-makers, contributors and developers have a shared understanding of the requirements/expectations of the service, and its measurement metrics. This speeds-up funding decisions and helps keep focus on the delivery business outcomes. The lightweight  and natural language nature of the documentation also aids future service iteration and evolution discussions.
See also
Rationale (optional)
Successfully used in large-scale projects where service clarity was a critical component. Used in an international context.
Developed based on similar concepts to Agile etc. – based on Cybernetics and Systems Thinking patterns.
Can plug into more traditional Value Chain and Process Swim-Lane views if desired: Thus helps bridge traditional ways of working with an InnerSource model.
Natural fit with a Microservices architecture.
Works well with any service type whether automated or manual, external or internal.
Can be applied to any size of ‘Service’: For example, can be applied to a mix software services developed, such as Microservices and extrnal Cloud services like SaaS and PaaS.
Known instances (optional)
DHL International, Hutchison Port Holdings (UK), YODEL PLC (UK), and CLP Power (Hong Kong) Ltd.

A post-merger Retail environment where multiple SaaS and PaaS macro services are integrated with a Microservices ecosystem.
11 Nov 2016 – 1st Review ready draft.
Nigel P.S.Green.


Thanks to the team at InnerSource for the tempalte format and advice on how to write a design pattern.


Comments and suggestions please.

Links to related posts:

The is blog and its contents is freely available for use under

Creative Commons :Attribution + ShareAlike License.

Please follow me on LinkedIn or Twitter for future posts.