Uma abordagem focada em decisões, não em tarefas

• Focar nas decisões

  • Uma citação de Every Page Is Page One trouxe uma grande mudança na abordagem de redação de documentação técnica
  • Na comunicação técnica, geralmente se fala em apoio à execução de tarefas, mas em muitos casos a informação de que as pessoas precisam para concluir uma tarefa não é como operar uma máquina, e sim informação para apoiar a tomada de decisões
  • Apenas documentar procedimentos não é suficiente
  • É preciso informar quais decisões o usuário deve tomar, quais são os resultados dessas decisões e direcioná-lo, sempre que possível, a recursos e materiais de referência que ajudem na tomada de decisão

Resumo do GN⁺

• Este texto enfatiza a importância do apoio à tomada de decisões na redação de documentação técnica
• É necessário ir além da simples descrição de procedimentos e ajudar o usuário a tomar decisões melhores
• Para quem escreve documentação técnica, é importante fornecer ao usuário o contexto e as informações de que ele precisa
• Como projetos do setor com funcionalidades semelhantes, Confluence e Notion são recomendados

[GN⁺]

Comentários do Hacker News

• Escrevo sobre a burocracia alemã, e concordo totalmente com essa abordagem.
  A maioria dos meus guias começa com “o que é isto, quem deve fazer e por que deve fazer”. Se você não garante que as pessoas estão fazendo a coisa certa pelos motivos certos, elas podem ir muito longe na direção errada.
  A maioria dos sites governamentais não explica esse tipo de coisa; eles só pedem o necessário para concluir o procedimento pelo qual são responsáveis. Não veem isso como parte de uma decisão maior e presumem que o usuário já chegou sabendo o que está fazendo.

  • Sobre o último parágrafo, o site gov.uk do Reino Unido faz isso muito bem. Há uma landing page que explica o procedimento e, só depois de avisos e ressalvas, você pode preencher o formulário de fato.
    Se você abrir o resultado do Google para renovar a carteira de motorista, https://www.gov.uk/renew-driving-licence, e clicar em “Start Now”, vai entender o que quero dizer.
    Do ponto de vista de um “usuário avançado”, às vezes parece um obstáculo, mas entendo que é preciso considerar todo mundo.
  • Esse comentário me faz pensar que você gostaria de Every Page Is Page One. A ideia central é que as pessoas podem chegar a qualquer página de um site de documentação, então todas as páginas precisam dar contexto rapidamente e ajudar o usuário a avaliar com facilidade se está no caminho certo.
    O título do livro vem daí. Qualquer página do site pode ser a primeira página para o usuário.
  • Eu gostaria que essa abordagem existisse em mais documentação técnica. Tenho tendência a sempre querer saber por que algo é feito de determinada forma, então acabo me desviando por caminhos paralelos e ficando mais lento.

• Combina bem com a forma como uso LLMs. Sempre peço opções e depois decido por conta própria qual delas faz mais sentido.
  No fundo, estou usando como uma espécie de documento mágico estranho, que cospe opções possíveis, imperfeitas mas úteis, a cada momento de tomada de decisão.

  • Pense em um aprendiz trabalhando com um artista famoso como Leonardo. O mestre desenha o contorno e os esboços, e os alunos preenchem as partes em branco sob supervisão. Às vezes o mestre também rouba as ideias dos alunos.
  • Você poderia dar um exemplo desse modo de uso?

• Muito bom. Curto, direto e perspicaz. Eu tendo a pensar em termos de visão geral, então não me importa apenas como fazer algo, mas também por que e como isso se conecta ao contexto maior.
  Incentivo os desenvolvedores a usarem bem o campo Description das stories e tarefas no Jira, incluindo um resumo de por que estamos fazendo aquele trabalho e como ele se conecta à visão geral. Alguns parecem não gostar, mas alguns gostam bastante.
  Eu fico satisfeito por oferecer a visão geral do projeto, e os desenvolvedores ficam satisfeitos porque, ao entendê-la, conseguem trabalhar de forma mais independente.

• Medir se a documentação ajuda as pessoas a tomar boas decisões parece muito mais difícil do que medir se ela as ajuda a concluir tarefas com sucesso.
  O motivo de se otimizar para documentação baseada em tarefas e procedimentos é que as empresas exigem que a equipe de documentação prove seu valor, há demanda por esse tipo de documentação, e existem muitas formas de medir e reportar isso em um período curto.
  Mas a pergunta “este conjunto de documentos ajudou alguém a criar a coisa certa da maneira certa?” é algo que até a própria organização tem dificuldade de responder sobre seu produto; ao abstrair isso para o efeito da documentação, fica muito nebuloso.
  Não quero dizer que não seja possível escrever documentação que ajude decisões, e sim que é muito difícil provar numericamente que você fez isso. Posso ranquear o quão bem diferentes conjuntos de documentos dão suporte a usuários que precisam tomar decisões e explicar os fundamentos, mas não sei bem como quantificar isso do jeito que a empresa quer.
  Também fico curioso sobre como a estrutura de um conjunto de documentos projetado para apoiar decisões seria diferente da documentação que apoia tarefas. As grandes categorias provavelmente seriam as mesmas — conceitos, referência e guias —, mas imagino que haveria muito mais documentação conceitual e mais espaço para contextualizar conceitos. Também espero mais dependências entre tópicos e mais referências cruzadas.

  • É interessante que o primeiro pensamento não seja “como posso usar isso para melhorar a documentação que escrevo?”, mas “como posso provar que isso melhora a documentação que escrevo?”. Parece que você trabalha em um ambiente bem rígido.
  • Em lugares onde você é livre para fazer o que acha melhor para os usuários, como em projetos pessoais, é bem provável que suporte à decisão seja usado como base da estratégia de documentação.
    Do ponto de vista de trabalhar com seriedade, se eu sinto que “suporte à decisão” é o melhor para o meu projeto, parece que tenho a obrigação de levar essa estratégia também para a documentação do trabalho.
    Felizmente não há gestores míopes me sufocando, mas, se eu precisasse convencer alguém no trabalho, faria assim: primeiro explicaria a lógica da estratégia. Suporte à decisão faz sentido e é convincente. A documentação de tarefas ainda é escrita, mas tarefas são apenas um subconjunto do suporte à decisão.
    Em seguida, apresentaria uma lista longa de exemplos em tickets de suporte, discussões em chats etc. em que a falta de suporte à decisão foi o problema. Por honestidade intelectual, mostraria a lista completa de tickets de suporte relacionados à documentação e, dentro dela, o subconjunto relacionado a suporte à decisão. Se a proporção não for desprezível, por exemplo 25%, então “suporte à decisão” merece uma análise mais profunda.
    Por fim, os stakeholders podem trazer exemplos do próprio trabalho deles. Algo como: “lembram como foi difícil decidir para qual CMS migrar?”

• Normalmente chamo isso de abordagem heurística.
  Sinto que o trabalho precisa de uma abordagem meio de lógica fuzzy. Só que ela funciona melhor quando o engenheiro já tem alguma experiência.
  Se a pessoa tem pouca experiência, mesmo sendo competente e inteligente, é preciso ser muito mais prescritivo.

  • Thinking in Bets foi um dos livros mais úteis para a forma como abordo engenharia de software. Não é um livro sobre código; é sobre como tomar decisões de forma eficaz em ambientes com informações limitadas.
  • Não entendi bem o que significa abordar o trabalho com uma abordagem de lógica fuzzy. Você poderia explicar um pouco melhor?

• Uma boa abordagem para tomar decisões em contexto de equipe é explicada por Rich Hickey aqui: https://www.youtube.com/watch?v=c5QF2HjHLSE
  O título da palestra é “Design in Practice”, mas na prática ela trata de tomada de decisão.

• “Trabalho é simplesmente tudo aquilo que precisa ser feito para ir de uma decisão à próxima.” — Venkatesh Rao, Tempo

• Venho defendendo algo parecido. Não basta descrever a ferramenta só em alto nível; especialmente porque as pessoas muitas vezes entram em modo marketing. É preciso falar sobre que problema aquela ferramenta foi projetada para resolver e quais trade-offs foram feitos nesse processo
  Assim fica muito mais fácil situar a ferramenta, as opções e modos disponíveis etc. dentro de um contexto, e avaliar rapidamente se ela serve para você

• Esse conselho me parece um pouco confuso. De quem é a decisão? É a decisão do criador da ferramenta ou a decisão do usuário?
  Em geral, parece uma simplificação excessiva. É mais útil primeiro entender se a documentação que você está escrevendo é para aprendizado, orientada a objetivos, para compreensão ou informativa [1]
  Por exemplo, se estou procurando a API de uma função, pode ser irritante ser inundado com informações sobre “decisões”
  1 - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...

  • A documentação deve sempre tratar das necessidades do usuário. Isso não desaparece. O mesmo vale para o Diataxis, os quatro quadrantes mencionados
    Acho que este texto ressoa porque expõe um ponto cego de duas estratégias bem conhecidas. Todo mundo tenta criar documentação centrada no usuário, e muitas equipes seguem o Diataxis, mas ainda assim têm dificuldade para concluir o trabalho usando a documentação
    Partir da perspectiva básica de que “a documentação deve apoiar decisões” pode ser um caminho para torná-la mais útil

• É importante saber como as pessoas usam meu sistema para tomar decisões. Vejo esse conhecimento como essencial para manter, expandir ou recriar o sistema
  Mas o texto propõe uma responsabilidade maior. A ideia é documentar o processo de tomada de decisão do usuário e informar contexto, opções e consequências das decisões
  Já trabalhei em um “sistema de apoio à decisão” com esse tipo de responsabilidade, e ele ficou complexo muito rapidamente. As pessoas gostam de discutir os resultados mesmo quando eles são conhecidos com 100% de certeza. Elas também não gostam de e-mails automáticos com incerteza, nem de uma documentação que exige uma escolha binária quando, na realidade, há muito mais opções
  Espero que, indo além deste texto, o livro trate do conceito de controle. Para documentar um comportamento, é preciso haver algum grau de garantia ou imposição sobre esse comportamento para que a documentação mantenha sua autoridade. Pessoalmente, vejo a ausência de autoridade e controle como um ponto cego comum e grande em iniciativas de escrita como https://www.plainlanguage.gov

  • Reaproveitando o que escrevi sobre este texto no r/technicalwriting, o ponto realmente importante na ideia de Baker é que a doutrina do ensino de documentação técnica está absolutamente centrada em tarefas
    Se você pesquisar redatores técnicos profissionais, muitos deles provavelmente acreditarão que “ajudar o usuário a realizar uma tarefa” é o principal objetivo da documentação, talvez O principal objetivo
    A breve citação de Baker é bastante radical no sentido latino de “voltar às raízes”, porque sugere que uma de nossas premissas fundamentais é muito insuficiente
    Pessoalmente, acho a ideia de Baker interessante porque ela estabelece um padrão muito mais alto do que o esperado atualmente da documentação técnica. Muitos documentos assumem que, se a tarefa foi documentada, “missão cumprida”, mas Baker parece dizer que isso não basta
    É claro que as tarefas ainda precisam ser documentadas, mas tarefas são um subconjunto das informações que compõem decisões
    Não me lembro se o livro de Baker discutia controle no sentido mencionado aqui. Para mim é uma ideia nova, então agradeço
    Um exemplo concreto de controle que me vem à mente é este: boa parte da minha documentação depende de páginas de outros projetos open source; se a qualidade dessas páginas externas for baixa, é bem possível que melhorá-las também deva ser minha responsabilidade. Muitas pessoas podem considerar documentos fora do próprio site como algo fora de sua responsabilidade, mas, se a intenção é realmente apoiar decisões, não importa quem hospeda aquele documento
    Talvez haja muito a aprender com a postura de ser um bom cidadão do open source