ThoughtWorks
  • Contato
  • Español
  • Deutsch
  • English
  • 中文
Visão geral
  • Cultura de engenharia, mentalidade de entrega

    Adote uma abordagem moderna ao desenvolvimento de software e entregue valor mais rapidamente

    Inteligência para tomada de decisões

    Explore seus dados para descobrir novas fontes de valor

  • Modelo de operação sem atritos

    Evolua a capacidade da sua organização de responder a mudanças

    Estratégia de plataforma

    Crie plataformas de tecnologia que se adaptam à sua estratégia de negócios

  • Design de experiência e inovação de produtos

    Planeje, execute e evolua rapidamente produtos e experiências excepcionais

    Parcerias

    Extraindo valor da nossa rede de parceiras para potencializar os resultados que entregamos a nossas clientes

Visão geral
  • Setor automotivo
  • Cleantech, energia e utilidade pública
  • Serviços financeiros e seguros
  • Saúde
  • Mídia
  • Organizações sem fins lucrativos
  • Setor público
  • Varejo e e-commerce
  • Viagem e transporte
Visão geral

Destaques

  • Tecnologia

    Uma análise abrangente de tecnologias e práticas de engenharia nas empresas

  • Negócios

    Mantenha-se em dia com as mais recentes tendências da indústria

  • Cultura

    Um espaço para conteúdo sobre desenvolvimento profissional e nossa visão sobre justiça social e inclusão

Ferramentas e Publicações Digitais

  • Technology Radar

    Um guia com opiniões firmes sobre as fronteiras da tecnologia

  • Perspectives

    Uma publicação para líderes digitais

  • Modelo de Fluência Digital

    Um modelo para priorizar as competências digitais necessárias para se navegar a incerteza

  • Decoder

    Um guia de A a Z sobre tecnologia para lideranças executivas

Todos os Insights

  • Artigos

    Visões de especialistas para ajudar seu negócio a crescer

  • Blogs

    Pontos de vista pessoais de ThoughtWorkers de todo o mundo

  • Livros

    Explore nossa vasta biblioteca

  • Podcasts

    Discussões instigantes sobre as últimas novidades em negócios e tecnologia

Visão geral
  • Processo de aplicação

    O que esperar de uma entrevista conosco

  • Pessoas em início ou mudança de carreira

    Comece sua jornada na tecnologia aqui

  • Vagas abertas

    Encontre oportunidades na sua região

  • Conecte-se

    Assine nossa newsletter mensal

Visão geral
  • Conferências e eventos
  • Diversidade e Inclusão
  • Notícias
  • Código aberto
  • Nossas lideranças
  • Transformação social
  • Español
  • Deutsch
  • English
  • 中文
ThoughtWorksMenu
  • Fechar   ✕
  • O que fazemos
  • Com quem trabalhamos
  • Insights
  • Carreiras
  • Sobre
  • Contato
  • Voltar
  • Fechar   ✕
  • Visão geral
  • Cultura de engenharia, mentalidade de entrega

    Adote uma abordagem moderna ao desenvolvimento de software e entregue valor mais rapidamente

  • Design de experiência e inovação de produtos

    Planeje, execute e evolua rapidamente produtos e experiências excepcionais

  • Modelo de operação sem atritos

    Evolua a capacidade da sua organização de responder a mudanças

  • Inteligência para tomada de decisões

    Explore seus dados para descobrir novas fontes de valor

  • Parcerias

    Extraindo valor da nossa rede de parceiras para potencializar os resultados que entregamos a nossas clientes

  • Estratégia de plataforma

    Crie plataformas de tecnologia que se adaptam à sua estratégia de negócios

  • Voltar
  • Fechar   ✕
  • Visão geral
  • Setor automotivo
  • Cleantech, energia e utilidade pública
  • Serviços financeiros e seguros
  • Saúde
  • Mídia
  • Organizações sem fins lucrativos
  • Setor público
  • Varejo e e-commerce
  • Viagem e transporte
  • Voltar
  • Fechar   ✕
  • Visão geral
  • Destaques

  • Tecnologia

    Uma análise abrangente de tecnologias e práticas de engenharia nas empresas

  • Negócios

    Mantenha-se em dia com as mais recentes tendências da indústria

  • Cultura

    Um espaço para conteúdo sobre desenvolvimento profissional e nossa visão sobre justiça social e inclusão

  • Ferramentas e Publicações Digitais

  • Technology Radar

    Um guia com opiniões firmes sobre as fronteiras da tecnologia

  • Perspectives

    Uma publicação para líderes digitais

  • Modelo de Fluência Digital

    Um modelo para priorizar as competências digitais necessárias para se navegar a incerteza

  • Decoder

    Um guia de A a Z sobre tecnologia para lideranças executivas

  • Todos os Insights

  • Artigos

    Visões de especialistas para ajudar seu negócio a crescer

  • Blogs

    Pontos de vista pessoais de ThoughtWorkers de todo o mundo

  • Livros

    Explore nossa vasta biblioteca

  • Podcasts

    Discussões instigantes sobre as últimas novidades em negócios e tecnologia

  • Voltar
  • Fechar   ✕
  • Visão geral
  • Processo de aplicação

    O que esperar de uma entrevista conosco

  • Pessoas em início ou mudança de carreira

    Comece sua jornada na tecnologia aqui

  • Vagas abertas

    Encontre oportunidades na sua região

  • Conecte-se

    Assine nossa newsletter mensal

  • Voltar
  • Fechar   ✕
  • Visão geral
  • Conferências e eventos
  • Diversidade e Inclusão
  • Notícias
  • Código aberto
  • Nossas lideranças
  • Transformação social
Blogs
Selecione um tema
Ver todos os tópicosFechar
Tecnologia 
Gestão de Projetos Agil Nuvem Entrega Contínua Ciência e Engenharia de Dados Defendendo a Internet Livre Arquitetura Evolutiva Design de Experiência IoT Linguagens, Ferramentas & Frameworks Modernização de sistemas legados Machine Learning & Artificial Intelligence Microsserviços Plataformas Segurança Testes de Software Estratégia de Tecnologia 
O negócio 
Serviços Financeiros Saúde Global Inovação Varejo Transformação 
Carreiras 
Dicas de Carreira Diversidade e Inclusão Transformação social 
Blogs

Topics

Escolha um tópico
  • Tecnologia
    Tecnologia
  • Tecnologia Visão Geral
  • Gestão de Projetos Agil
  • Nuvem
  • Entrega Contínua
  • Ciência e Engenharia de Dados
  • Defendendo a Internet Livre
  • Arquitetura Evolutiva
  • Design de Experiência
  • IoT
  • Linguagens, Ferramentas & Frameworks
  • Modernização de sistemas legados
  • Machine Learning & Artificial Intelligence
  • Microsserviços
  • Plataformas
  • Segurança
  • Testes de Software
  • Estratégia de Tecnologia
  • O negócio
    O negócio
  • O negócio Visão Geral
  • Serviços Financeiros
  • Saúde Global
  • Inovação
  • Varejo
  • Transformação
  • Carreiras
    Carreiras
  • Carreiras Visão Geral
  • Dicas de Carreira
  • Diversidade e Inclusão
  • Transformação social
Gestão de Projetos AgilTecnologia

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.
Posts relacionados
Design de Experiência

Entendendo como Design Thinking, Lean e Agile trabalham em conjunto

Jonny Schneider
Saiba mais
Gestão de Projetos Agil

Planejando seu caminho para a Fluência Ágil

Kelsey van Haaster
Saiba mais
Gestão de Projetos Agil

Ágil - Teoria vs. Prática

Abraham Kiggundu
Saiba mais
  • O que fazemos
  • Com quem trabalhamos
  • Insights
  • Carreiras
  • Sobre
  • Contato

WeChat

×
QR code to ThoughtWorks China WeChat subscription account

Mídia e relações públicas | Política de privacidade | Modern Slavery statement ThoughtWorks| Acessibilidade | © 2021 ThoughtWorks, Inc.