DDLC — Ciclo de Vida de Desenvolvimento de Documentação

Para quem não sabe, eu sou um redator técnico (ou technical writer, carinhosamente, TW). Eu faço isso desde, pelo menos, 2017; contudo, só virei CLT oficialmente em 2022. Resumindo, estou batendo no 7 anos de estrada no total e nos 3 anos de estrada corporativa/CLT. Nesse meio tempo eu passei por todo o tipo de problema em várias agências e empresas, acumulei um certo conhecimento e uma certa capacidade. A principal, até hoje, é sobre os ciclos de documentação técnica, DDLC (in english, maifriend).

Por isso mesmo eu resolvi escrever esse artigo, disfarçado de ensaio, que fala um pouco sobre essa métrica (adoro esse nome).

O Ciclo de Vida de Desenvolvimento de Documentação (Documentation Development Life Cycle, DDLC) tem 6 etapas principais:

1. Analise e planejamento.
2. Design/projeto (estruturação).
3. Desenvolvimento (escrita).
4. Edição e revisão (proofreading).
5. Publicação.
6. Manutenção.

Planejamento

1. Pedir demos ou realizar testes.
2. Gravar as reuniões.
3. Analisar a audiência.
4. Público-alvo:
5. PF ou PJ ou DEV?
6. Mapear as ferramentas necessárias.
7. Coletar informações com os SMEs.
8. Especialistas no produto.

Criando do Zero: O Poder da Tela em Branco

Iniciar uma documentação do zero é como ter uma tela em branco diante de si. A liberdade é emocionante, mas a direção é crucial. Comece definindo claramente os objetivos da documentação. Quem são as pessoas usuárias? Quais são suas necessidades específicas? Criar personas pode ser a chave para entender a audiência.

Além disso, estruture sua documentação de maneira intuitiva. Imagine que você é a pessoa usuária: como gostaria de encontrar as informações? Considere a criação de um índice claro, guias passo a passo e use exemplos práticos para ilustrar conceitos.

Por exemplo, o framework Django possui uma documentação exemplar para criar aplicativos web em Python. Seu planejamento robusto guia desde o básico até tópicos avançados, atendendo tanto iniciantes quanto pessoas desenvolvedoras experientes.

Atualizando a documentação existente

Atualizar uma documentação existente é como uma reforma em uma casa antiga. Requer cuidado e visão. Comece com uma auditoria detalhada. Quais partes estão desatualizadas? O que precisa ser simplificado ou expandido? O feedback das pessoas usuárias ou colegas de trabalho são valiosos aqui!

Considere adotar práticas ágeis. Fragmentar grandes atualizações em tarefas menores facilita o gerenciamento. Implemente um sistema de versionamento para rastrear alterações e manter transparência.

Dessa maneira, vamos pensar no guia de estilo da Microsoft, um exemplo de documentação contínua. Atualizações regulares garantem que a informação esteja sempre alinhada com as últimas práticas de escrita técnica.

Frameworks de documentação

Além do DDLC, existe um outro framework de processo de documentação que pode te ajudar no dia a dia de trabalho.

O Processo de Redação Técnica é uma estrutura fundamental composta por cinco etapas principais: Planejar, Estruturar, Escrever, Revisar e Publicar.

Na fase de Planejamento, o planejamento meticuloso é enfatizado, abordando aspectos chave como escopo do projeto, cronograma e o processo geral. Questões essenciais sobre o público, revisores, informações existentes, guias de estilo e modelos guiam essa etapa.

A segunda fase, Estrutura, envolve a criação de uma estrutura bem pensada para o seu documento, determinando sua ordem lógica. Seja usando uma estrutura narrativa, baseada em processos, biblioteca ou sistema, a colaboração com especialistas no assunto é crucial.

Escrever, a terceira etapa, requer a conversão de esboços em rascunhos, utilizando técnicas como KISS, Plain English e voz ativa. Envolvimento de especialistas no assunto e incorporação de sua experiência são cruciais durante esta fase.

A etapa de Revisão atua como a fase de polimento, envolvendo revisões formais, testes e edição rigorosa para garantir precisão e usabilidade.

A etapa final, Publicar, envolve o lançamento do documento, considerando logística como design gráfico, tradução e produção. Todo o processo é detalhado e pode ser encontrado no livro “Processo de Redação Técnica”, o qual fornece insights abrangentes e modelos prontos para uso para otimizar projetos de redação técnica.

Documentação como cultura

1. Encaixe a documentação como critério de aceite nas tarefas.
2. Prever a documentação na planning.
3. Criar templates de documentos específicos.
4. Buscar aliados que comprem a ideia de documentação.
5. Realizar testes na documentação.
6. É uma boa prática coletar feedbacks sempre que for possível.
7. Capacitar as pessoas a documentar.

Documentando o produto

1. Montar a estrutura visual da documentação.
2. Pode ser documento por documento ou de forma geral.
3. Mapear os assuntos para serem abordados.
4. Ferramenta: Octopus.do

Dicas para Aprimorar a Criação e Edição de Elementos Visuais em Documentações Técnicas

Dentre a área da documentação técnica, a importância de elementos visuais eficazes não pode ser subestimada. Vamos verificar algumas dicas práticas para elevar a qualidade de suas imagens, diagramas e vídeos, fornecendo uma abordagem centrada na objetividade.

Criando Imagens com Impacto

• Ferramentas Eficientes

Opte por ferramentas eficientes e focadas. Canva e Snappa são excelentes para iniciantes, enquanto o Photoshop oferece recursos avançados para usuários e usuárias mais experientes. Considere as necessidades específicas dentre seu projeto ao selecionar a ferramenta mais apropriada.

• Coerência Visual

Mantenha um padrão visual consistente em suas imagens. Escolha uma paleta de cores e um estilo que se alinhem à identidade visual da documentação. Isso não apenas aprimora a estética, mas também cria uma experiência visual coesa para a pessoa usuária. E é uma boa ideia verificar se há algum manual da marca ou solicitar auxílio do time de UX quanto a coerência visual.

• Captura Inteligente de Screenshots

Ao capturar screenshots, foque nas informações cruciais. Utilize ferramentas nativas do sistema, como o Snipping Tool no Windows ou comandos específicos no Mac (Command + Shift + 4 ou Command + Shift + 5), para garantir precisão e eficiência. A escolha cuidadosa do conteúdo destacado em uma captura pode fazer toda a diferença na compreensão por parte do usuário.

Diagramas que Simplificam

• Ferramentas Especializadas

O uso de ferramentas especializadas, como Draw.io e Lucidchart, é essencial para criar diagramas técnicos claros e profissionais. Ambas as plataformas oferecem recursos avançados que simplificam o processo de design e proporcionam resultados visuais impactantes.

• Sequência Lógica

Ao criar diagramas, é crucial organizar os elementos em uma sequência lógica. Isso facilita a compreensão da pessoa leitora, permitindo que siga uma linha de raciocínio clara. Evite sobrecarregar o diagrama com informações desnecessárias e busque uma estrutura simples e intuitiva.

• Iconografia Significativa

A escolha de ícones é uma parte vital na criação de diagramas. Opte por ícones universalmente reconhecidos e associados aos conceitos que deseja transmitir. Isso reduz a ambiguidade e garante que a mensagem seja compreendida de maneira consistente por diferentes públicos.

• Personalização e Profissionalismo

Explore as opções de personalização oferecidas pelas diferentes ferramentas. A capacidade de ajustar cores, estilos e tamanhos contribui para a criação de diagramas visualmente atraentes e alinhados com a identidade visual da documentação.

Criando Vídeos Informativos e Engajadores

• Roteiros Estruturados e Concisos

Ao produzir vídeos para sua documentação técnica, é crucial desenvolver roteiros estruturados e concisos. Divida o conteúdo em seções claras, fornecendo informações de maneira organizada. Isso facilita a compreensão e torna o vídeo mais eficaz.

• Demonstração Prática

Incorpore demonstrações práticas aos vídeos. Mostre, passo a passo, como realizar determinadas tarefas ou utilizar recursos específicos. Isso não apenas esclarece dúvidas, mas também oferece uma experiência prática para as pessoas usuárias.

• Edição Profissional

Invista na edição profissional dos vídeos. Utilize ferramentas como Adobe Premiere ou WonderShare Filmora para aprimorar a qualidade visual e sonora. Cortes precisos, transições suaves e uma trilha sonora adequada contribuem para um resultado final mais polido. Referente à edição, é essencial o apoio de profissionais especialistas, sendo que edição de vídeo não é algo tão simples.

• Legendas e Traduções

Inclua legendas nos vídeos para garantir acessibilidade a um público mais amplo. Além disso, considere a possibilidade de oferecer versões traduzidas para diferentes idiomas, aumentando a utilidade da documentação em um contexto global.

• Feedback Contínuo

Após disponibilizar os vídeos, avalie métricas de visualizações, comentários e sugestões para aprimorar futuras produções. Isso demonstra um compromisso com a melhoria constante da experiência da pessoa usuária.

Validação

• Manter o histórico das alterações.
• Feedbacks que não tem um acionável claro.
• Manter-se no escopo que fora definido.
• Ter uma tabela/formulário para receber feedback para a documentação.

Assistentes na validação e revisão da documentação

Na esfera do Technical Writing, a busca por eficiência e precisão é constante, e as ferramentas de Inteligência Artificial (IA) surgem como aliadas poderosas nesse cenário. Vamos explorar uma lista de ferramentas que estão contribuindo para dinamizar o trabalho de redação técnica:

1 — ChatGPT: Maravilhoso dentre a Comunicação Técnica**

Uma ferramenta de comunicação técnica que usa inteligência artificial para gerar textos técnicos relevantes e criativos. Você pode usar plugins para adicionar funcionalidades ao seu texto, como tradução, formatação, geração de imagens e muito mais, na versão paga. Quanto ao ChatGPT, temos uma versão gratuita (3.5) e versão paga (4.0). Na versão gratuita, não temos a possibilidade de inserção de imagens ou uso de plugins, enquanto na versão paga é possível.

2 — Smodin: Excelência em Artigos Técnicos**

O Smodin destaca-se como uma ferramenta de IA especialmente eficaz na produção de artigos técnicos. Sua capacidade de compreender a complexidade técnica e gerar conteúdo relevante o posiciona como um recurso valioso para escritores técnicos em busca de qualidade e originalidade, sendo que a ferramenta gera conteúdo original e livre de plágio, além disso, você pode escolher entre diferentes tópicos, idiomas e tons para personalizar seu texto E a ferramenta tem versão gratuita, limitada, e versão paga.

3 — Sudowrite: Aperfeiçoamento na Escrita Técnica com IA**

Sudowrite é uma ferramenta de melhoria do estilo, gramática e clareza que usa inteligência artificial para reescrever trechos do seu texto ou gerar novas ideias. Você pode usar o Sudowrite para superar o bloqueio criativo, melhorar o diálogo difícil ou expandir o seu esboço em um texto completo. A A ferramenta é paga e tem período de teste, o qual pode ser verificado aqui.

4 — Rytr: Assistência Diária na Escrita Técnica**

O Rytr oferece suporte à escrita técnica diária, proporcionando assistência rápida e eficaz em contextos técnicos específicos. Sua capacidade de gerar textos contextuais o torna uma ferramenta versátil para pessoas escritoras técnicas em diversas situações. A ferramenta tem versão gratuita ou versões pagas

5 — Chibi AI: Criatividade Impulsionada por IA na Escrita Técnica**

Uma ferramenta de criatividade impulsionada pela inteligência artificial que usa modelos personalizados ANI e um motor NLP refinado para entregar ótimos resultados na escrita técnica. Você pode usar o Chibi AI para explorar novas perspectivas e estilos no seu texto técnico, elevando sua originalidade. A ferramenta é paga, sendo possível testá-la tendo a possibilidade de uso de 2000 palavras, e você pode conferir os planos aqui.

6 — Surfer: Eficiência na Navegação da Escrita Técnica com IA**

Uma ferramenta dedicada à eficiência na escrita técnica que usa inteligência artificial para tornar o processo de redação técnica mais fluido e impactante. Você pode usar o Surfer para otimizar o seu conteúdo para SEO, análise da concorrência, palavras-chave relevantes e muito mais. E esta ferramenta somente tem versões pagas.

7 — Copy.AI: Automação Eficiente na Geração de Conteúdo Técnico**

A Copy.AI se destaca na automação eficiente da geração de conteúdo técnico. Sua capacidade de produzir textos técnicos de forma rápida e consistente a torna uma escolha notável para quem busca eficiência na criação de conteúdo técnico. A ferramenta tem versão gratuita ou versões pagas.

8 — Jasper: Tecnologia AI para Conteúdo Técnico Original**

O Jasper oferece uma abordagem única ao utilizar tecnologia AI para criar conteúdo técnico completo, original e livre de plágio de forma veloz e eficiente. Ideal para quem busca agilidade sem comprometer a qualidade técnica. É possível testar a ferramenta de maneira gratuita por 7 (sete) dias, mas as versões disponíveis são pagas.

9 — Copymatic: Excelente Opção no Mercado de IA para Textos Técnicos**

O Copymatic destaca-se como uma das principais opções no mercado para a criação de textos técnicos com a assistência da inteligência artificial. Sua reputação reflete a confiança que escritores e escritoras técnicos depositam em sua capacidade de gerar conteúdo técnico impactante. Quanto a ferramenta, é possível utilizar 10 (dez) créditos de maneira gratuita, mas há somente versões pagas após período de teste.

10 —Trinka: Assistência IA na Escrita Técnica Acadêmica**

O Trinka é um assistente de escrita com IA especialmente desenvolvido para escrita técnica acadêmica. Sua orientação específica atende às demandas rigorosas desse contexto técnico, proporcionando suporte valioso para técnicos, engenheiros e pesquisadores. A ferramenta tem versão gratuita ou versão paga.

Essas ferramentas representam apenas uma amostra do vasto ecossistema de IA para escrita técnica. Ao explorar essas opções, escritores e escritoras técnicos têm a oportunidade de aprimorar suas habilidades e alcançar novos patamares de eficiência na produção textual técnica. Este é apenas uma parte de uma jornada onde a colaboração entre humanos e máquinas redefine a área da escrita técnica.

Templates — Good Docs Project

Existem vários recursos online onde você pode encontrar templates de documentação para redação técnica, especialmente voltados para softwares, sendo o mais comum:

• The Good Docs Project:

O The Good Docs Project é um projeto que visa educar e capacitar as pessoas a criar documentação de alta qualidade para software de código aberto e outros domínios relacionados. O projeto oferece templates, recursos, melhores práticas e ferramentas para melhorar a documentação dos projetos.

O projeto se baseia em vários conceitos e princípios de escrita técnica, como os tipos de documentos, os modelos de maturidade, as estratégias de conteúdo e as diretrizes de escrita. Além disso, o projeto também fornece orientações sobre como personalizar e usar os templates para diferentes tipos de documentos.

O projeto tem como público-alvo pessoas desenvolvedoras de software que querem usar guias e templates para criar documentação para seus projetos, escritoras técnicas que querem estabelecer um framework de documentação usando templates estabelecidos e processos personalizados, e proprietárias dos projetos que precisam equilibrar as prioridades do projeto e entender o retorno sobre o esforço associado a diferentes estratégias de documentação.

O The Good Docs Project é uma iniciativa colaborativa que conta com a participação de vários grupos e projetos no GitLab, sendo que para participar, basta acessar The Good Docs Project.

Lembre-se, os templates de documentação são como bússolas, apontando na direção certa para que exista uma comunicação técnica realmente eficaz. Seja você uma pessoa novata na área ou uma veterana, os templates são aliados que simplificam partes que podem se mostrar complexas.

Diagrama DDLC

Ciclo de documentação

Tabela de feedback de documentação

Página Feedback Responsável Situação Acionável Cabe na sprint? Explicação Muito vazia, falta informação./ Stakeholder Em análise Nenhum. Feedback não ficou claro. Não Conceitos Me perdi um pouco durante a leitura. O vocabulário é difícil. As páginas são parecidas. Usuário Em análise Realizar testes A/B e de usabilidade na documentação. Sim

Manutenção

• Feedback de SMEs que não puderam ser encaixados na entrega da sprint.
• Análises de desempenho da documentação (métricas).
• Feedbacks de usuários e do público externo (fóruns, suporte, QA).
• Seguir o backlog do produto (FSR, SSGR, GAP).

Monitoramento de Feedback

Após a publicação, é crucial monitorar o feedback de usuários e usuárias. Isso pode ser feito através de comentários na própria documentação, pesquisas de satisfação do usuário, ou até mesmo através de análises de uso da documentação.

Por exemplo, a Microsoft mantém um sistema de comentários em sua documentação online, permitindo que as pessoas usuárias forneçam feedback direto sobre a utilidade e a clareza dos documentos.

Atualizações Regulares

A tecnologia está sempre mudando, e sua documentação deve acompanhar essas mudanças. Isso significa que você deve revisar e atualizar sua documentação regularmente para garantir que ela reflita as versões mais recentes do produto ou software.

Um exemplo real disso é a documentação do Python. A cada nova versão do Python, a documentação é atualizada para refletir as novas funcionalidades e alterações.

Melhoria Contínua

Além de atualizar a documentação para acompanhar as mudanças no produto, você também deve procurar maneiras de melhorar a qualidade da escrita, a clareza das explicações e a utilidade geral da documentação. Isso pode envolver a reescrita de seções confusas, a adição de exemplos mais claros ou a reorganização da estrutura da documentação para torná-la mais intuitiva.

Integração com Outros Recursos

Sua documentação não deve existir isoladamente. Integrá-la com outros recursos, como tutoriais em vídeo, pode aumentar seu valor para as pessoas usuárias.

Por exemplo, a documentação do software de edição de imagem Adobe Photoshop é complementada por uma vasta gama de tutoriais em vídeo disponíveis online.

Avaliação Regular

É importante realizar avaliações regulares de sua documentação. Isso pode envolver a realização de testes de usabilidade, a solicitação de feedback de especialistas no assunto ou a comparação de sua documentação com as melhores práticas do setor.

É necessário acompanhar sua documentação de forma bem próxima após a publicação, é preciso garantir que sua documentação continue a ser um recurso valioso para usuários e usuárias. Lembre-se, a escrita técnica é uma jornada, não um destino.

Métricas para documentação

Essas métricas servirão como indicadores de sucesso da documentação técnica. Essas métricas estarão além do portal de documentação.

Perguntas

1. Qual o resultado que eu espero alcançar com a documentação?
2. Quais os dados que me ajudam a analisar se cheguei no resultado esperado?

Aumentar a adoção da documentação

1. Número de pessoas que usam o produtos x Número de acessos à documentação.
2. % de satisfação com a documentação.
3. Ex: número de likes/dislikes nos documentos.

Diminuir casos de suporte

1. Número de tickets de suporte
2. Número de acessos à documentação.

Grupos de métricas

Podemos descrever em dois grupos:

Classificação das métricas da documentação

1. Numero de acessos.
2. Páginas mais visitadas e menos visitadas.
3. % de feedbacks positivos.

Classificação das métricas do usuário

1. Feedbacks na página da documentação.
2. Testes com usuários (usabilidade).

Fontes de dados

1. Ferramentas de métricas (como Google).
2. Pesquisas e formulários no site de documentação.
3. Entrevistas com os usuários, testes A/B, testes de usabilidade.

Métricas que podem ser analisadas

1. Conteúdos mais populares e eficazes:

Imagine escrever um guia para um aplicativo de culinária. As métricas revelam não apenas quantas vezes as receitas foram visualizadas, mas também por quanto tempo as pessoas usuárias permaneceram na seção de dicas de preparo. Esses dados contam a história de quais pratos são os favoritos, indicando os conteúdos mais eficazes e populares.

2. Engajamento e possibilidade de melhorias ou expansão:

Ao criar um manual para um novo software, métricas como tempo médio de leitura e taxas de cliques podem mostrar quais seções estão retendo a atenção das pessoas usuárias. Se a seção de solução de problemas tem um alto tempo médio de leitura, isso indica que usuários e usuárias estão com interesse em resolver problemas específicos, proporcionando um mapa para focar em melhorias ou expansões nessa área.

3. Feedbacks auxiliam a notar onde há pontos de confusão:

Considere um fórum online onde usuários e usuárias deixam avaliações e comentários sobre um manual técnico. Analisando métricas dessas interações, como a quantidade de feedback por página, é possível descobrir quais seções geram mais discussões. Esses números funcionam como uma conversa direta, indicando não apenas o que as pessoas usuárias gostam, mas também onde podem haver pontos de confusão.

4. Otimização de Documentação:

Empresas de tecnologia, como a Google, usam métricas para otimizar suas documentações. Ao analisar como usuários e usuárias interagem com guias online, essas empresas identificam os pontos de acesso mais comuns e ajustam a estrutura de seus documentos para tornar as informações mais acessíveis. Os dados moldam a experiência da pessoa usuária de maneira surpreendente.

5. Uso de Imagens para maior compreensão de Engajamento:

Pense em um gráfico de linha que mostra a evolução do número de downloads de um manual ao longo do tempo. Essa visualização clara e simples destaca o aumento ou a diminuição do interesse, permitindo uma análise rápida e envolvente. Gráficos como esses transformam os números em algo tangível, facilitando a compreensão do engajamento ao longo do tempo.