A importância da documentação no trabalho distribuído

Python Brasil [2021]

Agenda

Quem sou eu?

  • Vinicius Mendes

    • Back-end Python Engineer @ Loadsmart desde abr/21

    • Antes:

      • Solucione Sistemas
      • Globo.com
      • Dataprev
      • Professor Substituto na UFRN
Minha foto com minha estação de trabalho ao fundo

Eu na comunidade Python

Eu na comunidade Python

Python Brasil [5] em Caxias do Sul (2009)

Python Brasil [8] no Rio de Janeiro (2012)

Python Brasil 2014 em Porto de Galinhas

Python Brasil 2018 em Natal

Python Brasil 2021 em 🏠

Tá, mas e a documentação?

Manifesto ágil

Estamos descobrindo maneiras melhores de desenvolver software, fazendo-o nós mesmos e ajudando outros a fazerem o mesmo. Através deste trabalho, passamos a valorizar:

  • Indivíduos e interações mais que processos e ferramentas
  • Software em funcionamento mais que documentação abrangente
  • Colaboração com o cliente mais que negociação de contratos
  • Responder a mudanças mais que seguir um plano

Ou seja, mesmo havendo valor nos itens à direita, valorizamos mais os itens à esquerda.

Manifesto ágil

Estamos descobrindo maneiras melhores de desenvolver software, fazendo-o nós mesmos e ajudando outros a fazerem o mesmo. Através deste trabalho, passamos a valorizar:

  • Indivíduos e interações mais que processos e ferramentas
  • Software em funcionamento mais que documentação abrangente
  • Colaboração com o cliente mais que negociação de contratos
  • Responder a mudanças mais que seguir um plano

Ou seja, mesmo havendo valor nos itens à direita, valorizamos mais os itens à esquerda.

Contexto

Contexto

"Produto" -> "Requisitos": Demanda de produto "Requisitos" -> "Produto": Elicitação de requisitos "Produto" -> "Requisitos": Aprovação de requisitos "Requisitos" -> "Arquitetura": Documento de requisitos "Arquitetura" -> "Equipe de desenvolvimento": Documento de arquitetura "Equipe de desenvolvimento" -> "Equipe de desenvolvimento": Desenvolve o produto "Equipe de desenvolvimento" -> "Testes": Demanda de teste "Testes" -> "Testes": Plano de teste "Testes" -> "Testes": Suíte de teste "Testes" -> "Equipe de desenvolvimento": Relatório de teste "Equipe de desenvolvimento" -> "Equipe de desenvolvimento": Correção de bugs "Equipe de desenvolvimento" -> "Requisitos": Produto para homologação "Requisitos" -> "Produto": Roteiro de homologação "Produto" -> "Requisitos": Relatório de homologação

TL;DR

TL;DR

Quadro com processo em BPMN desenhado

Análise e planejamento

  • Entender o problema
  • Modelar o domínio
  • Modelar as operações
  • Qual o driver?
    • Time to market? Segurança? Performance?
  • Qual o volume esperado?
  • Identificar as possíveis integrações
    • Vai ser síncrona ou assíncrona? Por quê?
    • Vamos testar alguma tecnologia nova? Por quê?

Onde você guarda essas decisões?

Onde você guarda essas decisões?

Onde você guarda essas decisões?

  • Tire das cabeças das pessoas
  • Emails? Documentos físicos? Quadro?
  • Está acessível a todos?
    • Em um lugar conhecido por todos?
    • Fácil de encontrar?
    • Todos têm direito a acessar?
    • Na dúvida, qual a fonte da verdade?

Onde você guarda essas decisões?

Ferramentas

  • Armazenamento, compartilhamento e colaboração em arquivos
    • Google Drive, OneDrive, etc
  • Wikis
  • Chat instantâneo
    • Slack, Discord, Whatsapp, etc
  • Emails
  • Vídeoconferência
    • Zoom, Meet, Teams, etc

A tendência natural é espalharmos nossa documentação por cada uma dessas ferramentas.

Colaboração síncrona ou assíncrona?

Colaboração síncrona ou assíncrona?

Colaboração síncrona ou assíncrona?

Colaboração síncrona ou assíncrona?

Colaboração síncrona ou assíncrona?

Escalando times de engenharia via RFCs: anotando coisas

Roteiro

  • Planeje antes de construir algo novo
  • Capture esse plano em um pequeno documento escrito
  • Selecione algumas pessoas para comentar e aprovar esse plano
  • Disponibilize esse plano para todos os envolvidos
  • Dissemine a cultura na organização

Utilize ferramentas colaborativas

Utilize ferramentas colaborativas

Utilize ferramentas colaborativas

Utilize ferramentas colaborativas

Utilize ferramentas colaborativas

Utilize ferramentas colaborativas

Utilize ferramentas colaborativas

Utilize ferramentas colaborativas

Utilize ferramentas colaborativas

Utilize ferramentas colaborativas

Pull request no Github

  • Ferramenta familiar
  • Mantém histórico e rastreabilidade
  • Permite discussão contextual
  • Sugestões de melhoria
  • Aprovações
  • Integra ao pipeline de build

Github actions

Vamos praticar?

Vamos praticar?

Deu certo?

Benefícios

  • Melhor visibilidade das decisões
  • Tende a gerar decisões mais embasadas
  • Disseminação de conhecimento
  • Responsabilidade compartilhada
  • Facilita o processo de on-boarding

Benefícios

Documentação pode economizar tempo

  • Evite explicar várias vezes a mesma coisa
  • Se perceber que está fazendo isso, pare e documente
  • Passe a responder mais com um link pra documentação
  • Deixe bem documentado e você vai ter mais tempo para produzir mais features e documentações.

Qual é o seu público alvo?

Qual o contexto prévio necessário?

“A maioria dos seus usuários em potencial nunca saberá, porque eles nunca encontrarão seu projeto e, se o encontrarem, não terão ideia de como devem usá-lo.”

Livro: Docs for Developers: An Engineer’s Field Guide to Technical Writing (2021)
por Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne, David Nunez, Heidi Waterhouse

Documente a sua solução!