Crie e mantenha documentação sobre seu código ou as funcionalidades que você desenvolveu, tudo de forma rápida!

Veja como Alex usou Documentos para ajudar a equipe a melhorar funcionalidades com mais agilidade.

Conheça Alex

Alex é um desenvolvedor sênior em uma empresa de software baseada na nuvem. Ele percebe que algumas funcionalidades têm documentação muito limitada.

Alex nota que a equipe passa boa parte do tempo investigando como as funcionalidades funcionam diretamente pelo código do software. Isso reduz a capacidade da equipe de melhorar as funcionalidades existentes.

O desafio

As equipes de produto e engenharia trabalham com um cronograma muito apertado para lançar funcionalidades no produto. Os desenvolvedores têm tempo muito limitado para criar documentação sobre as novas funcionalidades.

A equipe não tem tempo para manter a documentação atualizada à medida que uma funcionalidade é aprimorada e os bugs são corrigidos.

Alguns desenvolvedores mais novos ficam frustrados com a falta de documentação. Eles têm dificuldade para aprender sobre o produto de forma eficaz.

Outros desenvolvedores sentem que passam mais tempo respondendo perguntas do que resolvendo problemas e escrevendo um código melhor.

A solução

Alex está trabalhando na melhoria de uma funcionalidade que não tem uma boa documentação. Ele decide criar um Documento no ClickUp com informações sobre a funcionalidade para servir de material de referência para os outros desenvolvedores.

Criar o documento e a estrutura de páginas

Alex decide que cada funcionalidade deve ter seu próprio Documento. Quando a equipe está trabalhando em uma funcionalidade, todas as informações relevantes ficam em um único documento independente.

Usar páginas dentro de um Documento permite que a equipe encontre respostas relevantes rapidamente, sem precisar vasculhar Documentos separados.

Alex cria algumas páginas dentro do Documento para estruturar o conteúdo com base no que a equipe precisa saber e pode estar buscando.

1. Resumo do produto
2. Código de front-end
3. Código de back-end
4. Infraestrutura
5. Aplicativo móvel
6. Testes e QA
7. Perguntas frequentes e solução de problemas

Títulos

Em cada página, Alex define títulos para deixar claro para a equipe de desenvolvimento onde cada informação deve ser inserida.

Resumo do produto

• Briefing do produto
• Descrição da funcionalidade
• Casos de uso
• Design de UI

Front-end

• Elementos de UI
• Estilos
• Tooltips

Back-end

• Rotas de API
• Esquema de banco de dados

Mobile

• iOS
• Android

Testes e QA

• Critérios de aceitação
• Testes automatizados de QA

Formatação

Alex combina as opções de formatação disponíveis nos Documentos do ClickUp para dar à documentação uma aparência consistente.

Código inline e blocos de código

Alex usa acentos graves ( ` ) para formatar texto como código inline e exibir linhas únicas de código, conforme o exemplo abaixo:

Para trechos de código maiores, Alex usa a Formatação de bloco de código ( /co ), conforme mostrado abaixo:

Opções de formatação do bloco de código

Defina seu bloco de código para usar a linguagem de programação que preferir!

1. Passe o cursor sobre o canto superior direito
2. Selecione sua linguagem preferida

Vincular e incorporar conteúdo

Agora o Documento de Alex tem texto, algumas capturas de tela e trechos de código úteis.

Está ficando bom, mas o Resumo do produto ainda está vazio.

A equipe de produto usa o Figma para criar designs e wireframes da interface do usuário. Alex usa o /Slash Command /figma para incorporar o design atualizado da funcionalidade diretamente na página de Resumo do produto.

Alex usa a menção @@ para vincular à tarefa de Epic no roadmap da equipe.

Criar um modelo

Alex salva o esboço do Documento como um Modelo para que a equipe possa criar rapidamente um Documento com as subpáginas e os títulos para outras funcionalidades.

1. Clique no ícone de configurações do Documento na barra lateral direita
2. Selecione Salvar como modelo

Alex preenche um Documento de exemplo usando o modelo para que a equipe tenha um padrão de referência de documentação.

Alex cria um novo Documento com base no modelo, preenche-o e compartilha com a equipe.

Prova de conceito

Alex apresenta o conceito de modelo de Documento para a equipe de engenharia na próxima reunião de equipe. Os outros desenvolvedores adoram o exemplo detalhado de documentação criado por Alex!

A equipe está preocupada com o tempo que pode levar para preencher os detalhes. Alex os desafia a escolher uma funcionalidade para mostrar a todos como é rápido criar documentação.

A equipe escolhe uma funcionalidade. Alex cria um Documento, aplica o modelo usando o Slash Command /temp e compartilha o link com todos na chamada.

Alguns desenvolvedores entram e começam a editar o Documento de forma colaborativa com Alex. Cada um preenche as páginas e seções com as quais está mais familiarizado.

Toda a equipe fica agradavelmente surpresa quando, após apenas 20 minutos, têm em mãos um rascunho bastante abrangente da documentação.

O resultado

A equipe decide testar o modelo e a documentação de Alex. No próximo Sprint, alguns desenvolvedores passam 30 minutos preenchendo a documentação da funcionalidade principal.

A documentação não está totalmente concluída. Há um esboço básico com detalhes suficientes para ajudar os outros desenvolvedores a começar a entender e melhorar a funcionalidade.

Após algumas semanas, escrever documentação vira parte importante da rotina da equipe de engenharia.

Com alguns ajustes e melhorias no modelo de Alex, o tempo gasto para criar e manter a documentação diminui.

Alex envia uma pesquisa e descobre que:

• Desenvolvedores mais novos se sentem mais confiantes ao trabalhar com o código quando há documentação disponível
• Desenvolvedores experientes recebem menos perguntas de colegas e das equipes de suporte ao cliente

É uma grande conquista para a equipe de engenharia! Em um evento da equipe, Alex recebe o título honorário de "Bibliotecário Residente e guardião do conhecimento".