Documentar nunca foi uma missão fácil. Seja pelo prazo do projeto, por falta de padronização, ou pela falta de um Tech Writer. Nesta talk, eu trago dicas de ferramentas, boas práticas e os principais drivers culturais que são necessários para ajudar times de tecnologia a se tornarem escaláveis e auto-organizáveis.
3. TechLead e Developer Advocate @Itaú
Caiçara & Dev Raiz
Pessoas & Comunidade
2 Verdades 1 Mentira
• Desenvolvedor Front-end desde 2006
• Sobrevivente IE6
• JS para efeitos no Mouse
• XHTML + HTML 4.01
• Angular SP
• Galactics Devs / ADPList
• Open / Inner source
• 1 - Participei de flashmob internacional de
lambada
• 2 - Já voei de balão
• 3 - Já fui o Fofão da carreta furacão
QUEM SOU
Paolo Almeida
Community Leader @AngularSP
Mentor Galactics Dev / ADPlist.org
5. NÃO TEM INGREDIENTE
SECRETO
SEGREDO
Não há uma “bala-de-prata” ou um único padrão
a ser seguido.
É necessário analisar a melhor forma e
ferramentas que atendam a necessidade do
time, produto e principalmente os usuários.
8. PAOLO ALMEIDA
“As pessoas não compram furadeira porque gostam, elas compram o furo na
parede e o quadro pendurado.”
“As pessoas não documentam porque necessariamente gostam, mas porque o usuário
precisa entender e ter sucesso no uso do produto”
9. DOCUMENTAÇÃO
CONTEXTUALIZANDO
FAQ
DOCUMENTAÇÕES TÉCNICAS
TUTORIAIS & TRILHAS
A documentação de software, é a instrução
precisa e clara sobre o funcionamento e o modo
de usar um determinado programa.
Podendo ser disponibilizada de várias formas,
através de textos, live codes, trilhas de
conhecimento, etc.
LIVE CODES & HANDS ON
11. CULTURA DE
DOCUMENTAÇÃO
POR QUÊ?
TEMPLATES E PADRÕES PARA
REUSO
GERAR CONSCIÊNCIA
DOCUMENTAÇÃO COMO ENTREGA
DO PRODUTO
Um grande passo para iniciar uma cultura de
documentação, é trazer o propósito e a
importância em seguir algumas boas práticas
para as pessoas que fazem parte da jornada de
desenvolvimento.
Fornecendo ferramentas, praticidade,
competitividade, conteúdos acessíveis e que
geram valor ao usuário.
PESSOAS INSPIRAM PESSOAS
12. PAUSA PARA O
FEEDBACK
BEBA ÁGUA!
PEGUE O BLOCO DE NOTAS
SE HIDRATE
enquanto isso..
BORA APRENDER!
bit.ly/feed-ng-itau
13. #04 DICAS PARA COMEÇAR A APLICAR E
INCENTIVAR A CULTURA DE DOCUMENTAÇÃO
NOS TIMES DE TECNOLOGIA.
QUICK WINS
14. #01 PESSOAS
DICAS
AUTOGERENCIAMENTO
NETWORK & MENTORIA
APRENDIZADO & COLABORAÇÃO
Comunique a importância de documentar
para o time. Engajar as pessoas para a prática
de documentar no dia a dia não é uma tarefa
fácil. Mas a constância é fundamental para garantir
que a documentação seja atualizada, efetiva e
acessível.
15. #01 PESSOAS
DICAS
SENIORES COMO INSPIRAÇÃO
TECH WRITER
PESSOAS ESCALAM CONHECIMENTO
Comunique a importância de documentar
para o time. Engajar as pessoas para a prática
de documentar no dia a dia não é uma tarefa
fácil. Mas a constância é fundamental para garantir
que a documentação seja atualizada, efetiva e
acessível.
16. #02 BOAS PRÁTICAS
DICAS
GUIAS & TRILHAS
CODE REVIEW
ORGANIZE AS INFORMAÇÕES
Incentivar as boas práticas é fundamental.
Entender quem é a audiência da documentação
e ter uma boa escrita técnica para conseguir.
17. #03 FERRAMENTAS
DICAS
TEMPLATES & GUIAS DE ESTILO
README & CONTRIBUTING
SEMANTIC RELEASE &
CONVENTIONAL COMMITS
Como parte facilitadora e fundamental no
incentivo a cultura de documentação, as
Ferramentas e Padronizações já fornecem
uma estrutura para as pessoas desenvolvedoras
focarem principalmente no conteúdo.
18. #04 EFETIVIDADE
DICAS
MÉTRICAS & ANALYTICS
CANAIS PARA FEEDBACK
INCENTIVE A COLABORAÇÃO
Mas, de nada adiantaria, se não entendermos
O quão efetiva está sendo a documentação
para o usuário.
É importante se perguntar:
Está resolvendo alguma dor? Qual? Como?