ThoughtWorks
  • Contact
  • Español
  • Português
  • Deutsch
  • 中文
Go to overview
  • Engineering Culture, Delivery Mindset

    Embrace a modern approach to software development and deliver value faster

    Intelligence-Driven Decision Making

    Leverage your data assets to unlock new sources of value

  • Frictionless Operating Model

    Improve your organization's ability to respond to change

    Platform Strategy

    Create adaptable technology platforms that move with your business strategy

  • Experience Design and Product Capability

    Rapidly design, deliver and evolve exceptional products and experiences

    Partnerships

    Leveraging our network of trusted partners to amplify the outcomes we deliver for our clients

Go to overview
  • Automotive
  • Cleantech, Energy and Utilities
  • Financial Services and Insurance
  • Healthcare
  • Media and Publishing
  • Not-for-profit
  • Public Sector
  • Retail and E-commerce
  • Travel and Transport
Go to overview

Featured

  • Technology

    An in-depth exploration of enterprise technology and engineering excellence

  • Business

    Keep up to date with the latest business and industry insights for digital leaders

  • Culture

    The place for career-building content and tips, and our view on social justice and inclusivity

Digital Publications and Tools

  • Technology Radar

    An opinionated guide to technology frontiers

  • Perspectives

    A publication for digital leaders

  • Digital Fluency Model

    A model for prioritizing the digital capabilities needed to navigate uncertainty

  • Decoder

    The business execs' A-Z guide to technology

All Insights

  • Articles

    Expert insights to help your business grow

  • Blogs

    Personal perspectives from ThoughtWorkers around the globe

  • Books

    Explore our extensive library

  • Podcasts

    Captivating conversations on the latest in business and tech

Go to overview
  • Application process

    What to expect as you interview with us

  • Grads and career changers

    Start your tech career on the right foot

  • Search jobs

    Find open positions in your region

  • Stay connected

    Sign up for our monthly newsletter

Go to overview
  • Conferences and Events
  • Diversity and Inclusion
  • News
  • Open Source
  • Our Leaders
  • Social Change
  • Español
  • Português
  • Deutsch
  • 中文
ThoughtWorksMenu
  • Close   ✕
  • What we do
  • Who we work with
  • Insights
  • Careers
  • About
  • Contact
  • Back
  • Close   ✕
  • Go to overview
  • Engineering Culture, Delivery Mindset

    Embrace a modern approach to software development and deliver value faster

  • Experience Design and Product Capability

    Rapidly design, deliver and evolve exceptional products and experiences

  • Frictionless Operating Model

    Improve your organization's ability to respond to change

  • Intelligence-Driven Decision Making

    Leverage your data assets to unlock new sources of value

  • Partnerships

    Leveraging our network of trusted partners to amplify the outcomes we deliver for our clients

  • Platform Strategy

    Create adaptable technology platforms that move with your business strategy

  • Back
  • Close   ✕
  • Go to overview
  • Automotive
  • Cleantech, Energy and Utilities
  • Financial Services and Insurance
  • Healthcare
  • Media and Publishing
  • Not-for-profit
  • Public Sector
  • Retail and E-commerce
  • Travel and Transport
  • Back
  • Close   ✕
  • Go to overview
  • Featured

  • Technology

    An in-depth exploration of enterprise technology and engineering excellence

  • Business

    Keep up to date with the latest business and industry insights for digital leaders

  • Culture

    The place for career-building content and tips, and our view on social justice and inclusivity

  • Digital Publications and Tools

  • Technology Radar

    An opinionated guide to technology frontiers

  • Perspectives

    A publication for digital leaders

  • Digital Fluency Model

    A model for prioritizing the digital capabilities needed to navigate uncertainty

  • Decoder

    The business execs' A-Z guide to technology

  • All Insights

  • Articles

    Expert insights to help your business grow

  • Blogs

    Personal perspectives from ThoughtWorkers around the globe

  • Books

    Explore our extensive library

  • Podcasts

    Captivating conversations on the latest in business and tech

  • Back
  • Close   ✕
  • Go to overview
  • Application process

    What to expect as you interview with us

  • Grads and career changers

    Start your tech career on the right foot

  • Search jobs

    Find open positions in your region

  • Stay connected

    Sign up for our monthly newsletter

  • Back
  • Close   ✕
  • Go to overview
  • Conferences and Events
  • Diversity and Inclusion
  • News
  • Open Source
  • Our Leaders
  • Social Change
Blogs
Select a topic
View all topicsClose
Technology 
Agile Project Management Cloud Continuous Delivery  Data Science & Engineering Defending the Free Internet Evolutionary Architecture Experience Design IoT Languages, Tools & Frameworks Legacy Modernization Machine Learning & Artificial Intelligence Microservices Platforms Security Software Testing Technology Strategy 
Business 
Financial Services Global Health Innovation Retail  Transformation 
Careers 
Career Hacks Diversity & Inclusion Social Change 
Blogs

Topics

Choose a topic
  • Technology
    Technology
  • Technology Overview
  • Agile Project Management
  • Cloud
  • Continuous Delivery
  • Data Science & Engineering
  • Defending the Free Internet
  • Evolutionary Architecture
  • Experience Design
  • IoT
  • Languages, Tools & Frameworks
  • Legacy Modernization
  • Machine Learning & Artificial Intelligence
  • Microservices
  • Platforms
  • Security
  • Software Testing
  • Technology Strategy
  • Business
    Business
  • Business Overview
  • Financial Services
  • Global Health
  • Innovation
  • Retail
  • Transformation
  • Careers
    Careers
  • Careers Overview
  • Career Hacks
  • Diversity & Inclusion
  • Social Change
Agile Project ManagementTechnology

Four goals of Agile documentation: Part one

Birgitta Böckeler Birgitta Böckeler

Published: Jul 11, 2018

“Working software over comprehensive documentation” is one of the Agile Manifesto’s four value statements. You may well be one of those people who believe that documentation is a waste of effort because it’s outdated as soon as it’s created. You might believe that your code is self-documenting or that UML diagrams belong in the 90s. But it’s a mistake to think there’s no value in documentation.

The manifesto style phrasing of “A over B” has a footnote of course: “While there is value in items on the right, we value the items on the left more.” So while there actually is value in the documentation, we value working software more. And we definitely value working software more than comprehensive documentation.

So what level of documentation is enough? As with so many things in software development: it depends. There’s, unfortunately, no fixed set of rules to apply. But to determine how to do just enough of any activity, focusing on the value that activity creates is a good start. Ask yourself why you should create a piece of documentation, and then balance and prioritize the effort according to its value.

This two-part article will talk about and give examples for four communication benefits documentation can bring in an agile software delivery team. The first two are covered in Part One, the others in the follow-up piece.

Documentation is a vast area. It can be done in lots of different mediums, describing many different aspects of software for various stakeholders. Here, we focus on how developers can use high-level documentation to communicate inside a team, and with direct stakeholders. All of these are things that can complement the documentation already provided by code, scripts, and tests.

1. Create a common understanding

I often catch myself working under the assumption that everybody on the team has the same understanding of what we are doing. “Surely the view of the architecture in my head is clear to everybody?” That would imply we don’t have to write these seemingly obvious things down or have a sketch on the wall. This is a fallacy that, in my experience, especially more tenured developers on the team are prone to.


Architecture show-and-tell

To verify how accurate our assumptions about common understanding really are, you need to get each team member to lay out their understanding. You can do an exercise in your team where you break into groups, have everybody put together their view of the architecture and then present back. This can help surface misunderstandings and complement each other’s knowledge. You also come out of it with an overview picture to evolve and use in future discussions and onboardings.

Figure 1: Creating shared values
The wall of common understanding I always like to reserve some space for a “wall of common understanding” with overview pictures of core concepts. The contents of this wall depend on the software at hand. There’s usually some form of a systems overview with external dependencies, frequently a component and technology stack overview. If the environment setup is elaborate, you might put that up; if it’s really simple, you might decide not to waste space on it.

Example of a wall of common understanding
Figure 2: Example of a wall of common understanding

Regardless of what ends up on this wall, it’s important to set a space constraint. For example, if the team is co-located, this could be a piece of wall space that holds six or eight sheets of paper. Then you fill that space with everything that you believe everybody on the team should know about the state of the system you’re building. The space constraint is useful because we can usually only keep a limited amount of things at the forefront of our minds anyway. The goal here is to identify the essence of what everybody should know so that you can work towards your goals efficiently. Doubling the space just because you’re working on a very large system will dilute that purpose.


Identifying candidates for the wall

  • What are you always explaining to new team members within their first week?
  • What do you often need to explain to stakeholders to give them a high-level overview of the system?
  • What does not change frequently?

2. Surface and understand complexity

As developers, we strive for simplicity in our software, and “self-documenting,” well readable code. In spite of this, we’ll always end up with parts that aren’t trivial, yet critical. Creating documentation for these parts, in particular, is important. That makes it not only easier to explain them, but also helps to evaluate if the implementation makes sense, and to uncover accidental complexity.


Infographics

The format of “infographics” has helped me with this type of documentation. Take an example of a team building an offline-first web application. In this architecture, we had modules for data synchronisation, data model migrations, and conflict, all of which are inherently complex concepts. We built them in the beginning, and then rarely touched them as the development continued. Using infographics to describe these concepts gave us a concise overview without simplifying things too much and hiding the complexity. They’re a mix of graphics and text, with a relatively high level of detail. The reader is supposed to take some time to read and absorb them. This is in contrast to the more high-level overview diagrams mentioned before, where you usually aim for a quick overview.

Figure 3: Example of an infographic


Identifying candidates for infographics

  • Complicated things you don’t touch frequently, but every time you do touch them, you have a hard time remembering how it works. The more critical a component like this is to your application, the more important it is to document it.
  • You just designed a new part of the system, and you want to check if the design’s simple enough? If you can’t come up with an understandable infographic, that might be a design smell. The thought process of creating the documentation can help make the design even better.
What type of information you put on the wall or turn into infographics can also depend on factors like the seniority of the team, the frequency of change in team composition, the type of application, phase of the project (e.g., how old is the code), or your business domain.
 

Paper widget kits

Another aid I’ve used to facilitate the frequent explanation of a non-trivial part of the architecture is a set of paper widgets. You can use them to build up a picture step by step, as part of a conversation. Our “explain our data model” kit for example contained screen sketches, data entities on index cards, and a set of cards representing our data import jobs. We used it to not only explain the model, but also talk about where the data came from, and what it was used for.


 

Identifying candidates for widget kits

  • Parts of the software that has a lot of history, and lots of things “between the lines” that are hard to put in writing.
  • Things that I prefer having a conversation about, instead of giving somebody a wiki entry to read.
  • Things with a large scope, where a step-by-step explanation helps understanding.
In Part Two of this article, I’ll discuss how to help our future selves make more informed decisions, and how to use documentation to create empathy. I’ll also describe strategies to try and keep documentation up to date.
Related blogs
Experience Design

Understanding how Design Thinking, Lean and Agile Work Together

Jonny Schneider
Learn more
Agile Project Management

Road-mapping Your Way to Agile Fluency

Kelsey van Haaster
Learn more
Agile Project Management

Agile - Theory vs. Practice

Abraham Kiggundu
Learn more
  • What we do
  • Who we work with
  • Insights
  • Careers
  • About
  • Contact

WeChat

×
QR code to ThoughtWorks China WeChat subscription account

Media and analyst relations | Privacy policy | Modern Slavery statement ThoughtWorks| Accessibility | © 2021 ThoughtWorks, Inc.