1) O documento discute a importância e métodos de documentação de projetos de software, incluindo a criação de documentação, diagramas e modelos como C4. 2) É explicado que mesmo projetos ágeis precisam de alguma documentação básica e os benefícios dela, como onboarding de novos membros e comunicação. 3) São apresentadas ferramentas como PlantUML e Mermaid para criar diagramas de arquitetura e manter a documentação atualizada através de "diagramas como código".

1. Documentação de projetos

2. Quem sou eu?

3. O que veremos hoje

4. O que veremos hoje
Documentação

5. O que veremos hoje
Documentação
Readme

6. O que veremos hoje
Documentação
Readme
C4 Model

7. O que veremos hoje
Documentação
Readme
C4 Model
Diagram As Code

8. Documentar?

9. Software em funcionamento mais que
documentação abrangente - Manifesto Ágil

10. Alguns “traduzem” essa frase como:
NÃO documentar nada!

11. Na maioria dos casos
precisamos documentar, nem
que seja o básico!

12. Por quê documentar?

13. Por quê documentar?
Onboarding de pessaos no time

14. Por quê documentar?
Onboarding de pessaos no time
Não ficar dependendo de só uma pessoa

15. Por quê documentar?
Onboarding de pessaos no time
Não ficar dependendo de só uma pessoa
Facilidade na comunicação / discussões

16. Por quê documentar?
Onboarding de pessaos no time
Não ficar dependendo de só uma pessoa
Facilidade na comunicação / discussões
Troubleshooting mains rápido

17. Por quê documentar?
Onboarding de pessaos no time
Não ficar dependendo de só uma pessoa
Facilidade na comunicação / discussões
Troubleshooting mains rápido
…

18. Mas esta sempre desatualizado…

19. Mesmo assim, teremos uma ideia de onde
estamos! E não vai ser tudo que vai estar
desatualizado.

20. Por onde começar?

21. Readme

22. O que colocar?

23. O que colocar?
Qual o objetivo do projeto

24. O que colocar?
Qual o objetivo do projeto
O que precisa ser instalado

25. O que colocar?
Qual o objetivo do projeto
O que precisa ser instalado
Como rodar o projeto

26. O que colocar?
Qual o objetivo do projeto
O que precisa ser instalado
Como rodar o projeto
Dicionário de termos

27. O que colocar?
Qual o objetivo do projeto
O que precisa ser instalado
Como rodar o projeto
Dicionário de termos
Configurações, Migrations, Deploy…

28. Exemplo
Fluxo De Caixa

29. Geradores
https://readme-gen.vercel.app/app
https://www.freecodecamp.org/news/how-to-
write-a-good-readme-file/
https://readme.so/editor

30. Dúvidas?

31. E a documentação da
arquitetura?

32. Problema

33. Padronização!

34. Fluxo, Arquitetura, Cloud…

36. Mesma solução diferentes desenhos

39. UML?

40. Complexidade
Principalmente na criação, são muitas regras!

41. 🚀C4 - Model 📐

42. Camadas - 4

43. Primeiro, visão geral; depois, amplie e filtre; em
seguida, detalhes sob demanda - Ben
Shneiderma, 1996

44. The Eyes Have It: A Task by Data Type Taxonomy
for Information Visualizations

46. Vai dando zoom nas camadas

51. System Context
Tem como objetivo ser o ponto de entrada, uma
visão geral!

52. System Context - Público alvo
Pessoas ténicas e não tecnicas

53. System Context - Person

54. System Context - Software systems

55. System Context - Enterprise boundary
Opcional

57. System Context - Interações

58. System Context

59. Container
Ter uma visão mais detalhada da arquitetura, quais
os serviços fazem parte, e como se comunicam

60. Container - Público alvo
Pessoas técnicas, dev, dba, qa…

61. Container - Person

62. Container - Sistema existente

63. Container - Boundary
Opcional

65. Container

66. Container - “Clientes”

67. Container - Banco de dados

68. Container - Filas / Tópicos
Há controvérsias

69. Container

71. Component
O mais próximo do código, usado para discutir
fluxos dentro do sei app/api…

72. Component - Público alvo
Time que vai desenvolver a solução

73. Component
O unico diferente

74. Component

75. Code

76. Code

78. Ferramentas

79. Miro

80. Excalidraw

81. Como manter atualizado?

82. Diagram As Code

83. Plant UML

84. Mermaid

85. Problema

86. Bora pra prática!

87. Livros

88. The software guidebook

89. The C4 model for visualising software
architecture

90. Por onde começar?

91. Crie um bom Readme

92. Crie seu Diagrama de Contexto

93. De o primeiro passo
Documente!

94. Contatos