A documentação do software é apenas um conjunto de artigos. Mas mesmo eles podem ser frustrantes. Primeiro, você procura a instrução certa por um longo tempo. Depois, você tenta entender um texto pouco claro. Você faz o que está escrito, mas o problema não é resolvido. Você busca outro artigo, fica nervoso... Depois de uma hora, você desiste de tudo e vai embora. É assim que funciona uma documentação ruim. O que a torna assim e como corrigir isso — leia a seguir.
Na nossa antiga documentação, havia muitos problemas. Há quase um ano, estamos reformulando-a para que o cenário descrito acima não afete nossos clientes. Veja, e .
Problema 1. Artigos confusos e mal escritos
Se na documentação é impossível entender, qual é o seu valor? Mas ninguém escreve artigos confusos de propósito. Eles surgem quando o autor não considera a audiência e o objetivo, enche linguiça e não revisa o texto para erros.
- Audiência. Antes de escrever um artigo, é preciso pensar no nível de preparação do leitor. É lógico que em um artigo para iniciantes não se deve pular etapas básicas ou deixar termos técnicos sem explicação, enquanto que em um artigo sobre uma funcionalidade rara, destinada apenas a profissionais, não se deve descrever o significado da palavra PHP.
- O objetivo. Outra coisa que é melhor pensar com antecedência. O autor deve estabelecer um objetivo claro, definir a ação útil do artigo, decidir o que o leitor fará após lê-lo. Se isso não for feito, o resultado será uma descrição por si só.
- Excesso de informações e erros. Muitas informações desnecessárias e jargões, erros e typos dificultam a compreensão. Mesmo que o leitor não seja um perfeccionista gramatical, a negligência no texto pode afastá-lo.
Considere os conselhos acima, e os artigos se tornarão mais claros — garantido. Para fazer ainda melhor, utilize nossas .
Problema 2. Os artigos não respondem a todas as perguntas
É ruim quando a documentação não acompanha o desenvolvimento, não responde a perguntas reais e os erros não são corrigidos por anos. Esses problemas não são tanto do autor, mas da organização dos processos dentro da empresa.
A documentação não acompanha o desenvolvimento
A funcionalidade já está em lançamento, o marketing planeja destacá-la, e de repente percebemos que ainda não há um novo artigo ou tradução na documentação. Tivemos que adiar o lançamento por causa disso. Podemos solicitar quantas vezes forem necessárias que todos passem as tarefas para os redatores técnicos a tempo, mas isso não funcionará. Se o processo não for automatizado, a situação vai se repetir.
Fizemos algumas mudanças no YouTrack. A tarefa de escrever um artigo sobre a nova funcionalidade é atribuída ao redator técnico no momento em que a opção começa a ser testada. Na mesma hora, o marketing toma conhecimento para se preparar para a promoção. As notificações também chegam pelo nosso mensageiro corporativo Mattermost, portanto, é impossível perder atualizações dos desenvolvedores.
A documentação não reflete as demandas dos usuários
Estamos acostumados a trabalhar assim: a funcionalidade é lançada, nós falamos sobre ela. Descrevemos como ativar, desativar e ajustar configurações. Mas e se o cliente usar nosso software de uma maneira que não previmos? Ou se ele encontrar erros que não consideramos?
Para que a documentação seja o mais completa possível, recomendamos analisar os chamados de suporte, perguntas em fóruns temáticos e buscas nos motores de pesquisa. Os tópicos mais populares devem ser enviados aos redatores técnicos para que eles completem os artigos existentes ou escrevam novos.
A documentação não é aprimorada
É difícil fazer tudo perfeitamente de imediato, sempre haverá erros. Podemos contar com o feedback dos clientes, mas é improvável que eles relatem cada erro de impressão, imprecisão, artigo confuso ou que não foi encontrado. Além dos clientes, os funcionários também leem a documentação, então eles veem os mesmos erros. Isso pode ser aproveitado! É necessário criar condições nas quais seja fácil relatar um problema.
Temos um grupo no portal interno onde os funcionários deixam comentários, sugestões e ideias sobre a documentação. O suporte precisa de um artigo, mas ele não existe? Um testador notou uma imprecisão? Um parceiro reclamou para os gerentes de desenvolvimento sobre erros? Tudo vai para este grupo! Os redatores técnicos corrigem algumas coisas imediatamente, transferem outras para o YouTrack, e algumas são levadas em consideração. Para que o assunto não desapareça, de tempos em tempos lembramos a todos sobre a existência do grupo e a importância do feedback.
Problema 3. É necessário procurar muito tempo pelo artigo que precisamos
Um artigo que não pode ser encontrado não é melhor do que um artigo que não existe. O lema de uma boa documentação deve ser "Fácil de pesquisar, fácil de encontrar". Como alcançar isso?
Organizar a estrutura e definir o critério de seleção de temas. A estrutura deve ser o mais transparente possível, para que o leitor não se pergunte "Onde posso encontrar este artigo?". Resumindo, existem duas abordagens: a partir da interface e a partir de tarefas.
- A partir da interface. O conteúdo replica as seções do painel. Era assim na antiga documentação da ISPsystem.
- A partir de tarefas. Os títulos dos artigos e seções refletem as tarefas dos usuários; nos cabeçalhos, quase sempre há verbos e respostas à pergunta "como fazer". Estamos agora migrando para esse formato.
Qualquer que seja a abordagem que você escolher, certifique-se de que o tema corresponda às solicitações dos usuários e seja abordado de maneira que o usuário resolva sua dúvida.
Implementar uma busca centralizada. No mundo ideal, a busca deve funcionar mesmo quando você comete erros de digitação ou confunde o idioma. Nossa busca no Confluence ainda não consegue proporcionar isso. Se você tem muitos produtos e a documentação é geral, adapte a busca para a página em que o usuário está. No nosso caso, a busca na página principal abrange todos os produtos, mas se você já está em uma seção específica, buscará apenas nos artigos dessa seção.
Adicionar um índice e "breadcrumbs". É bom ter um menu e breadcrumbs em cada página — o caminho do usuário até a página atual com a possibilidade de voltar a qualquer nível. Na antiga documentação da ISPsystem, era necessário sair do artigo para acessar o índice. Isso era inconveniente, então corrigimos isso na nova versão.
Adicionar links no produto. Se as pessoas vêm repetidamente ao suporte com a mesma dúvida, é razoável adicionar uma dica com a solução na interface. Se você possui dados ou entendimento de quando o usuário enfrenta o problema, você também pode notificá-lo por meio de uma newsletter. Assim, você demonstra cuidado e alivia a carga do suporte.
À direita na janela pop-up, há um link para o artigo sobre a configuração do DNSSEC na seção de gerenciamento de domínios do ISPmanager
Configurar links cruzados dentro da documentação. Artigos que estão interligados devem ser "linkados". Se os artigos formarem uma sequência, adicione setas para frente e para trás ao final de cada texto.
A probabilidade é que a pessoa comece a buscar respostas para sua pergunta não com você, mas nos mecanismos de busca. É frustrante se não houver links para a documentação por razões técnicas. Portanto, cuide da otimização para buscadores.
Problema 4. Layout ultrapassado prejudica a percepção
Além de textos ruins, o design pode arruinar a documentação. As pessoas estão acostumadas a ler materiais bem formatados. Blogs, redes sociais, mídia — todo o conteúdo é apresentado de maneira não apenas bonita, mas também agradável à leitura e ao olhar. Portanto, é fácil entender a frustração de alguém que vê um texto como na captura de tela abaixo.
Neste artigo, há tantas capturas de tela e destaques que elas não ajudam, mas apenas atrapalham a percepção (a imagem é clicável)
Não é aconselhável transformar a documentação em um longread cheio de efeitos, mas é necessário considerar as regras básicas.
Layout. Defina a largura do texto principal, fonte, tamanho, cabeçalhos e margens. Envolva um designer, e para aceitar o trabalho ou lidar com isso sozinho, leia o livro de Artem Gorbunov "Tipografia e Layout". Nele, é apresentada apenas uma visão sobre o layout, mas é suficientemente completa.
Destaques. Determine o que precisa de ênfases no texto. Normalmente, isso inclui o caminho na interface, botões, trechos de código, arquivos de configuração, blocos "Preste atenção". Defina como serão esses destaques e registre no regulamento. Tenha em mente que quanto menos destaques, melhor. Quando há muitos, o texto "ruído". Ruído é causado até mesmo por aspas, se usadas com muita frequência.
Capturas de tela. Combine com a equipe em quais situações capturas de tela são necessárias. Não é necessário ilustrar cada passo. Uma grande quantidade de capturas de tela, inclusive de botões individuais, prejudica a percepção e arruína o layout. Defina o tamanho, bem como o formato dos destaques e legendas nas capturas de tela, e registre no regulamento. Lembre-se de que as ilustrações devem sempre corresponder ao que foi escrito e ser relevantes. Mais uma vez, se o produto for atualizado regularmente, acompanhar cada mudança será complicado.
Comprimento do texto. Evite artigos excessivamente longos. Divida-os em partes e, se isto não for possível, adicione um índice com links âncora no início do artigo. Uma forma simples de tornar o artigo visualmente mais curto é ocultar detalhes técnicos, necessários apenas para um público restrito, sob um spoiler.
Formatos. Combine vários formatos nos artigos: texto, vídeo e imagens. Isso melhorará a percepção.
Não tente encobrir problemas com um design bonito. Sinceramente, nós também esperávamos que a 'embalagem' salvasse a documentação desatualizada – não funcionou. Os textos continham tanto ruído visual e detalhes desnecessários que as normas e a nova formatação eram impotentes.
Muito do que foi descrito acima dependerá da plataforma que você utiliza para a documentação. Para nós, por exemplo, é o Confluence. Também tivemos que trabalhar um pouco com ele. Se você está interessado, leia a história do nosso desenvolvedor web: .
Por onde começar as melhorias e como sobreviver
Se a sua documentação é tão extensa quanto a da ISPsystem e você não sabe por onde começar, comece pelos problemas mais sérios. Os clientes não entendem a documentação - melhore os textos, crie normas e treine os escritores. A documentação está desatualizada - cuide dos processos internos. Comece pelos artigos mais populares sobre os produtos mais demandados: pergunte ao suporte, veja as análises do site e as pesquisas nos motores de busca.
Vamos ser claros - não será fácil. E também não será rápido. A menos que você esteja apenas começando e já esteja fazendo as coisas certas. Uma coisa sabemos com certeza - com o tempo, ficará melhor. Mas o processo nunca acabará :-).
Fonte: habr.com
