Crie e mantenha rapidamente a documentação sobre seu código ou as funcionalidades que você desenvolveu!

Saiba como Alex utilizou os Docs para permitir que sua equipe melhorasse as funcionalidades mais rapidamente.

Conheça Alex

Alex é um desenvolvedor sênior em uma empresa de software baseada na nuvem. Eles descobrem que alguns recursos têm documentação muito limitada.

Alex percebe que a equipe gasta uma boa parte do tempo investigando como as funcionalidades funcionam diretamente do código do software. Isso diminui a capacidade da equipe de melhorar os recursos existentes.

O desafio

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

A equipe não tem tempo para manter a documentação, pois um recurso é aprimorado com o tempo e os bugs são eliminados.

Alguns desenvolvedores mais novos estão frustrados pela falta de documentação. Estão encontrando dificuldades para aprender sobre o produto de forma eficaz.

Outros desenvolvedores sentem que passam mais tempo respondendo perguntas do que resolvendo problemas e escrevendo códigos melhores.

A solução

Alex está trabalhando na melhoria de um recurso que não possui uma documentação adequada. Eles decidem criar um Documento ClickUp com informações sobre o recurso como material de referência para outros desenvolvedores.

Crie a estrutura do documento e da página

Alex decide que cada recurso deve ter seu próprio Doc. Quando a equipe está trabalhando em um recurso, todas as informações relevantes estão contidas em um único documento.

Usar páginas dentro de um Documento permite que a equipe encontre respostas relevantes rapidamente sem procurar e pesquisar em 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 procurando.

1. Resumo do Produto

2. Front código final

3. Código de back-end

4. A infraestrutura

5. Aplicativo móvel

6. Testes e QA

7. Perguntas frequentes e solução de problemas

Dica: Procure por páginas específicas ou conteúdo dentro de um Doc usando a função de Busca!

Títulos

Em cada página, Alex define títulos para que fique claro para a equipe de desenvolvimento quais informações devem ser colocadas onde.

Resumo do Produto

• Resumo do produto

• Estrutura do recurso

• Casos de uso

• Design de interface do utilizador

Front End

• Elementos da interface do usuário

• Estilos

• Dicas de ferramentas

Back End

• Rotas de API

• Esquema de banco de dados

Celular

• iOS

• Android

Testes e QA

• Critérios de aceitação

• Testes automatizados de QA

Formatação

Alex utiliza uma combinação das opções de formatação disponíveis nos Documentos ClickUp para dar à sua documentação uma aparência e sensação consistentes.

Código Inline e Blocos de Código

O Alex usa marcas de trás ( `` ) para formatar o texto como código em linha para exibir linhas individuais de código, conforme mostrado no exemplo abaixo:

Para trechos de código maiores, Alex utiliza 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 codificação que você escolher!

1. Passe o mouse sobre o canto superior direito

2. Selecionando seu idioma preferido

Vincule e incorpore 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 utiliza o Figma para projetar e criar o wireframe da interface do usuário. Alex usa o comando /Slash /figma para incorporar o design atualizado do recurso diretamente na página Resumo do produto.

Alex usa @@ para mencionar e vincular à tarefa Épica no roadmap da equipe.

Criar um modelo

Alex salva o esboço do documento como um modelo para que a equipe possa criar um documento de forma rápida e fácil com as subpáginas e os títulos de outros recursos.

1. Clique no ícone de configurações de Doc na barra lateral direita

2. Selecione Salvar como Modelo

Alex preenche um exemplo de Doc usando o modelo para que a equipe tenha um padrão ouro de documentação como exemplo.

Alex cria um novo Doc baseado no modelo, preenche 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 do Alex!

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

A equipe decide sobre um recurso. Alex cria um documento, aplica o modelo usando o comando /temp Slash e compartilha o link com todos na chamada.

Alguns desenvolvedores entram e começam a editar colaborativamente o Documento com Alex. Todos preenchem as páginas e seções com as quais estão mais familiarizados.

Toda a equipe fica agradavelmente surpresa quando, após apenas 20 minutos, eles criaram um rascunho bastante abrangente da documentação.

O resultado

A equipe concorda em fazer um teste com o modelo e a documentação do Alex. No próximo Sprint, alguns desenvolvedores passam 30 minutos preenchendo a documentação para o recurso principal.

A documentação ainda não está completa. Há um esboço básico com detalhes suficientes para ajudar outros desenvolvedores a começar a entender e aprimorar o recurso.

Depois de algumas semanas, o hábito de escrever documentação se tornou uma parte importante das tarefas da equipe de engenharia.

Com algumas alterações e melhorias no modelo do Alex, o tempo gasto na criação e manutenção de documentações diminui.

Alex realiza uma pesquisa e descobre que:

• Os desenvolvedores mais novos se sentem mais confiantes ao trabalhar com o código quando há documentação disponível

• Os desenvolvedores experientes percebem menos perguntas de seus colegas e das equipes de suporte ao cliente

É uma grande vitória para a equipe de engenharia! Em um evento da equipe, Alex recebe o título honorário de bibliotecário residente do "e o detentor do conhecimento".