This document discusses the importance of system descriptions based on case studies of software companies. It describes seven cases that demonstrate a range of approaches to documentation, from no documentation to detailed documentation. The document advocates that system descriptions should include diagrams, logical and physical structures, data and code architecture, and related business processes and personas. They are important for development, maintenance, handovers, and enabling new employees to understand complex systems.

1. © Balandor Oy 2017
System Description asSystem Description as
a Map for Developmenta Map for Development
Tom Weckström, Balandor OyTom Weckström, Balandor Oy
FiSMA Scope Manager ForumFiSMA Scope Manager Forum
12.12.201712.12.2017

2. © Balandor Oy 2017
Balandor Oy – Management Advisor
●
Lean- and Agile -thinking as a basis
● Packaged services as a solution, e.g.:
•Offering Audit
•CX assessment
•Scalability booster
●
Systems thinking behind all the solutions.
● More info: http://balandor.fi/en/

3. © Balandor Oy 2017
System

4. © Balandor Oy 2017

5. © Balandor Oy 2017

6. © Balandor Oy 2017

7. © Balandor Oy 2017

8. © Balandor Oy 2017

9. © Balandor Oy 2017
Which of these systems isWhich of these systems is
the most likely to bethe most likely to be
produced without aproduced without a
description document?description document?

10. © Balandor Oy 2017
Description”a spoken or written account of
a person, object, or event”
- Apple Dictionary -
ORIGIN: from Latin
descriptio(n-), from describere
‘write down’.

11. © Balandor Oy 2017
System DescriptionSystem Description
IS it needed?IS it needed?
WHAT would YOU NEED in it?WHAT would YOU NEED in it?
WHAT does it HELP to have one?WHAT does it HELP to have one?

12. © Balandor Oy 2017
Map

13. © Balandor Oy 2017
Being parachuted to unknownBeing parachuted to unknown
territory...territory...

14. © Balandor Oy 2017
No sign of where you are...No sign of where you are...

15. © Balandor Oy 2017
You start walking and findYou start walking and find
a road and a man with aa road and a man with a
car and a map...car and a map...

16. © Balandor Oy 2017
Case examples from aCase examples from a
few software companiesfew software companies

17. © Balandor Oy 2017
Case 1:Case 1:
● Very little original system description - only if customers asked,
was something created
●
High-level architecture diagram worked as a starting point. The
next level was source code.
● Code base was slow to learn and considered complicated.
●
Later, automated tools were used to create better understanding
of the function calls, code base, etc.

18. © Balandor Oy 2017
Case 2:Case 2:
● System architeture drawings were used.
●
Also some written material about software components existed.
●
Verbose written documentation was used in the planning phase
and wasn't often updated later on.
● Some senior developers used color-coded system diagrams to
quickly communicate status of large new sub-system development.

19. © Balandor Oy 2017
Case 3:Case 3:
● A well documented system was easily handed over for
maintenance, thanks to the customer's system description
template.
● Architecture drawings helped us plan major system upgrades.
●
All the used 3rd
party software components were listed, and kept
up-to-date.

20. © Balandor Oy 2017
Case 4:Case 4:
●
No drawings, but a bunch of URLs for each system component.
● No code base documentation. Fragmented code-base with layers
of old and new code, different languages, etc.
●
Knowledge about the system was verbal folklore.
● One sub-system had detailed drawings, and a list of components
used, which enabled sub-contracting efficiently.

21. © Balandor Oy 2017
Case 5:Case 5:
● No manually created or automated system descriptions were
available - "Ask the architect and he will tell you".
●
Even after more than a year working on the system, a developer
might not know, which parts of the system are affected by his
code.
●
Monolithic approach: "Most of the stuff is handled in this big
black box very few of us understand".

22. © Balandor Oy 2017
Case 6:Case 6:
● Not even a high-level description existed.
●
Employee turnover was high, and new people were dependent on
very few old-timers, who knew the system.
● When a technical architecure assessment was done by an external
consultant, the work started with interviewing the software
architects and photographing the whiteboard drawings.
●
Customers' quality criteria mandated better descriptions for some
products.

23. © Balandor Oy 2017
Case 7:Case 7:
●
Developers took initiative and used the system description as an
architecture planning tool.
●
Architecture was very long-lasting (10+ years) and efficient.
●
Everyone understood easily, what part of the system another
person was talking about, even years later.
● Good system description and automated tools for updating the
code base documentation helped adding a new OEM source code
business model.
● System descriptions were effectively used as a part of induction
training for new employees.

24. © Balandor Oy 2017
What would you like toWhat would you like to
see in Systemsee in System
Descriptions?Descriptions?

25. © Balandor Oy 2017
I have seen these:
●
Code architecture: modules, classes, APIs, services
● Logical structure
●
Physical structure
●
Data flow
● Protocol descriptions
●
System Maintenance process / responsibilities
●
Own and third party systems that are related/connected
● Terminology

26. © Balandor Oy 2017
I missed these:
●
Business Processes
● Personas
●
More Diagrams – A picture tells a thousand words

27. © Balandor Oy 2017
System DescriptionSystem Description
IS it needed?IS it needed?
WHAT would YOU NEED in it?WHAT would YOU NEED in it?
WHAT does it HELP to have one?WHAT does it HELP to have one?

28. © Balandor Oy 2017
References
https://systemsandus.com/foundations/what-is-a-system/
https://en.wikipedia.org/wiki/Software_architecture
https://en.wikipedia.org/wiki/Map
https://en.wikipedia.org/wiki/History_of_cartography
https://fi.wikipedia.org/wiki/Tietoj%C3%A4rjestelm%C3%A4arkkitehtuuri
https://startupsventurecapital.com/you-fired-your-top-talent-i-hope-youre-happy-cf57c41183dd

29. © Balandor Oy 2017
Tom Weckström
tom@balandor.fi
@TomWexi
+358 40 77 230 77
Balandor Oy
Got a Map?

30. © Balandor Oy 2017
Tom Weckström
tom@balandor.fi
040 – 77 230 77
Balandor Oy
Valmiina tasapainoiseen muutokseen?