Agora vamos falar então, a gente já deu motivos para escrever, já falou um pouquinho de como revisitar, e a gente vai voltar um pouco sobre isso daqui a pouco, mas vamos falar como que eu preencho esse documento, o que eu tenho que ter lá. E aí a primeira, a resposta talvez vocês não gostem tanto, que é a seguinte, o que eu vou mostrar aqui, as seções que vão ser descritas aqui, não representam um guia a ser seguido. Elas são apenas exemplos e recomendações. Eu gosto até de uma... de falar que é uma prescrição. Eu estou prescrevendo que vocês... eu estou prescrevendo essa sessão. Mas não necessariamente você precisa seguir isso, tá? Vocês vão ver que eu coloquei em boas práticas e tudo mais, mas se alguma delas não fizer sentido, você pode simplesmente ignorá-las. Ou se alguma delas você tiver uma outra maneira de se representar, tudo bem, não tem maneira certa ou errada de se fazer. E aí a gente começa com uma coisa que talvez seja um dos mais importantes, que são os cabeçalhos. Os cabeçalhos vão ter o nome das pessoas autoras do documento, e aí, lembrando que pode ter uma pessoa autora ou várias pessoas autoras do documento, qual autora. A gente vai ter pessoas que revisaram o documento, porque depois que a gente escreveu o documento, a gente vai passar isso em processo de revisão, a gente vai ver esse processo mais ou menos como é que é. Você tem o estado do documento e acredite, isso é muito importante, porque quando eu leio um documento, eu quero saber se aquilo ainda é um rascunho, se aquilo já foi proposto, se foi aprovado, se aquilo foi rejeitado. se foi aprovado, se aquilo foi rejeitado, e a data de criação, porque às vezes eu posso estar lendo documentos velhos, e aí normalmente, e aí não é regra, a gente pode ter datas de criação ou datas de atualização. E aí a gente mantém, toda vez que eu fizer uma operação, eu troco, inclusive dependendo da ferramenta que você utilizar, você pode, dependendo da ferramenta que você utiliza, você pode inclusive deixar isso pela própria ferramenta. Esse controle de versão do documento ser feito pela própria ferramenta que você usa. E aí, só adiantando um pouco, eu fiz o... daqui pra frente nas estruturas, a gente vai ter um seguinte modelo, tá? Eu vou ter uma explicação do que é aquele determinado campo, da que é aquela seção, em seguida, algumas dicas que eu vou dar para como preencher aquela seção de uma maneira um pouco melhor. Todas essas dicas vêm da minha própria experiência, tá? De analisar ZendDoc, revisar ZendDoc e escrever também ZendDoc. E depois eu vou ir com um exemplo prático e aí eu trago no próximo slide aqui um exemplo de como ficaria isso na prática tá bom? minha dica sobre cabeçalho parece coisa simples, mas é importante não deixe de atualizar o estado do documento como eu disse, é sempre importante saber se um documento já foi aprovado se foi rejeitado, se já foi proposto se a pessoa ainda está escrevendo e está em rascunho. Porque a partir do momento que você começa a escrever, aquilo já está em um estado que é o rascunho. E já pode ser compartilhado por outras pessoas. Envolva e peça revisão para pessoas com maior senoridade das áreas relevantes, segurança, infraestrutura, plataforma, ou times envolvidos e impactados. Como eu disse, às vezes você está mudando um contrato de uma PI, então se algum time for impactado naquilo, é bom você já envolver e já pedir para que elas revisem. Quando eu estou dizendo para envolver, envolver no sentido de pedir uma revisão. Você escrever essa solução e pedir para que eles revisem. E aí pode ser, às vezes você está com um pouco de dúvida na sua infraestrutura ou nas considerações de segurança, se algum campo, se a gente tem, por exemplo, algum documento de segurança que já trata as vulnerabilidades e ameaças, e aí eu posso estar fazendo algo que pode infringir isso, então, no sentido que traga essas pessoas para revisarem, tá, inclua essas pessoas. para revisar, inclua essas pessoas. E uma outra coisa, independente da plataforma que você fizer, se ela tiver alguma maneira de indexar aquilo, é bom você adicionar rótulos ou tags. Eu particularmente tenho usado muito Confluence e o Confluence tem como você colocar tags, então normalmente eu coloco tags e às vezes tags relacionados ao assunto daquele time doc. Porque em algum momento se eu precisar buscar eu posso fazer essa busca e já ter um resultado um pouco mais assertivo. E aí na prática esses cabeçalhos vão ficar mais ou menos assim, eu tenho o título, nesse caso é um sistema de gerenciamento de tarefa, autores, nesse caso foram dois, duas pessoas, João Silva e Maria Souza, os revisores foram Pedro Santos e Ana Oliveira. A data de criação foi 15 de agosto de 2022 e o status desse design doc que ele está proposto. Aqui não é o design doc inteiro, eu pude só o cabeceiro para destacar e o uso das tags design doc e gerenciamento de tarefas. Se em algum momento eu tiver outros designs posteriores a esse, eu consigo acessar por tags similares. Coloquei o cabeçalho, a primeira coisa que normalmente aparece, e aí repara que eu estou falando que normalmente aparece, não necessariamente, como eu disse, é fácil e a maioria de vocês julgar melhor, porque é um documento relativamente informal. Então, é uma visão geral, que é um texto breve, de alto nível, do que o um documento relativamente informal. Então, é uma visão geral, que é um texto breve, de alto nível, do que o seu documento se trata. E ele visa trazer o que esperar na leitura do documento, no sentido que uma pessoa que leia aquela visão geral, ele pode decidir continuar ou não a leitura do documento. Porque às vezes não é o que ele procura, não é aquela solução técnica dele, não é o problema que ele estava procurando ver, como aquela tomada de decisão que ele estava procurando. E aí, nesse caso da visão geral, eu dou algumas dicas que são legais. Primeiro, não faça grande, porque é geral. Ele não é para ter detalhes, é para ser bem específico. Então, não deve conter detalhes. Tipicamente, ele vai ser um parágrafo, no máximo dois, tá? O mais habitual é que seja um só, porque a ideia é que ele seja sucinto e simplesmente expresse, beleza, por exemplo, a gente vai dar um exemplo aqui de um BFF. Vocês vão ver que o meu exemplo é mais ou menos assim, eu estou adicionando um BFF novo no sistema de vendas online. E o interessante é que ao mesmo tempo que você não deve conter detalhes, mas você deve ter detalhes suficientes para que a pessoa que mesmo sem ler o resto do documento e que tenha algum contexto ou conhecimento prévio, ele consiga entender do que se trata. Então, aí eu peguei um exemplo prático, que é esse design doc apresenta a criação de um novo backend for frontend, ou BFF, para um sistema de vendas online, que agora irá oferecer um aplicativo novo. Estão vendo que eu não detalho muito do problema, o que eu tenho problema de não ter um BFF, porque eu não estou detalhando motivadores de eu colocar esse BFF ou coisas assim. Eu simplesmente estou passando uma visão de forma geral, motivadores de eu colocar esse BFF ou coisas assim. Eu simplesmente estou passando uma visão de forma geral, que é, o meu documento vai falar de um novo front-end, de um novo back-end para front-end, para o sistema de vendas online. Aqui eu vou ter o sistema de vendas online um pouco genérico, para não ser um exemplo genérico. E que agora ele vai oferecer um aplicativo móvel. Repara que eu não tenho detalhes. Vamos passar, então. Feita a visão geral, a gente entra no... Beleza. Lembra que eu falei que a visão geral não deve conter detalhes? Aqui a gente começa a colocar detalhes. Aqui a gente vai começar a colocar motivadores, que é a questão do escopo e de contexto. Então, ó, eu vou descrever o cenário ao qual o sistema está inserido, os motivadores da escrita do documento. Por que eu estou escrevendo esse documento? Porque eu tenho um problema. Qual é esse problema? Eu preciso informar para as pessoas, então, voltando, eu tenho descreve o cenário ao qual o sistema está inserido, os motivadores da escrita do documento e informações para entendimento do contexto do problema que está inserido. E aqui é o momento onde a gente pode falar, ah, hoje a gente tem um determinado CRM legado, ele é feito em uma tecnologia tal, a gente tem tal dívida técnica. Repara que eu não estou colocando a solução. Eu estou te dando o contexto. Eu estou colocando o problema. Eu ainda não estou falando que eu vou trocar o que eu tenho para algo novo. Eu estou simplesmente te inserindo na mesma realidade que eu tenho. Falando quais são as tecnologias, as minhas dívidas técnicas, todos os problemas que eu tenho. E o objetivo principal dessa parte de escopo e contexto é que os leitores sejam atualizados com o que eu estou fazendo. Mais algum conhecimento prévio. E aí vocês viram que em todo momento eu falo mas não preciso de conhecimento prévio. Algum conhecimento prévio pode até ser assumido. E algumas informações detalhadas podem ser vinculadas. Mas sempre toma cuidado de não exigir muito desse conhecimento prévio. Porque senão uma pessoa futuramente pode ler e não conseguir encaixar as peças. Então as dicas que eu dou nesse ponto é seja sucinto. Não fique dando muita rodada. Até porque Dendoc não é para ser um escrito de um livro. A ideia é que seja simples. Não coloca nem objetivo, nem solução. A ideia aqui, que nem eu disse, é trazer escopo e contexto. A gente está inserido numa cloud tal, uma tecnologia tal, minhas dívidas técnicas são essas, o meu problema que eu quero resolver é esse. Encara tudo isso como um plano de fundo. E aqui vem uma coisa, eu gosto de fazer uma analogia, que um design doc, ele é que nem contar uma história. Ele tem um começo e meio fim. Você está vendo que eu comecei por uma visão geral, eu agora estou começando a te introduzir naquele cenário, é como se eu tivesse te falado, eu vou contar a história de tal coisa. Beleza, nesse Eu vou contar a história de tal coisa. Beleza. Nesse scope, contexto, eu já estou te dando o cenário. O nosso cenário é esse. Daqui a pouco a gente vai realmente contar a história e mostrar a solução. E por fim eu preciso dar algumas conclusões. E aí vocês vão ver que tudo isso se encaixa e a ideia é que esse documento seja como uma história. Nossa, mas isso vai ficar grande. Vocês vão ver que não é bem assim. Vocês viram que até agora, olha só, eu tenho algumas linhas aqui, um parágrafo na visão geral. Agora o meu contexto, eu vou mostrar para vocês como é que ficou. É o mesmo sistema. A gente vai, acho que provavelmente já está vendo a apresentação, com o mesmo contexto, o mesmo design doc, que contexto, o mesmo design nós, que é o sistema de vendas online da empresa XZ.Z ele busca aprimorar a experiência do usuário no meio de lançamento de um novo aplicativo móvel. Então, repara que eu estou te introduzindo naquele cenário que é, a gente vai lançar um aplicativo móvel e a experiência do usuário não pode ser prejudicada. No entanto, a atual API REST do sistema possui um payload demasiadamente grande para ser possuído em dispositivos móveis. Então, a visão geral não fala que vai ser feito um backup. Mas no scope eu não sinto isso. Repare que eu só estou citando o problema. Eu falei, ó, a gente tem um problema que é o payload. Na hora que eu colocar uma aplicação móvel, isso vai ser um problema para a gente. Eu tenho um API REST já, hoje, no sistema. Como que eu posso resolver esse