A documentação do software é apenas um conjunto de artigos. Mas até eles podem te deixar louco. Primeiro, você passa muito tempo procurando as instruções necessárias. Então você entende o texto obscuro. Você faz o que está escrito, mas o problema não foi resolvido. Você procura outro artigo, fica nervoso... Uma hora depois você desiste de tudo e vai embora. É assim que funciona a documentação ruim. O que o torna assim e como consertar - leia abaixo do corte.
Havia muitas deficiências em nossa documentação antiga. Estamos reformulando há quase um ano para que o cenário descrito acima não afete nossos clientes. Olhar, и .
Problema 1: artigos pouco claros e mal escritos
Se a documentação é impossível de entender, qual é o sentido disso? Mas ninguém escreve artigos incompreensíveis de propósito. Acontecem quando o autor não pensa no público e no propósito, derrama água e não verifica se há erros no texto.
- Público. Antes de escrever um artigo, é preciso pensar no nível de preparação do leitor. É lógico que em um artigo para iniciante você não deve pular as etapas básicas e deixar os termos técnicos sem explicação, mas em um artigo sobre um recurso raro que só os profissionais precisam, você deve explicar o significado da palavra PHP.
- Meta. Mais uma coisa para pensar com antecedência. O autor deve definir um objetivo claro, determinar o efeito útil do artigo e decidir o que o leitor fará após lê-lo. Se isso não for feito, você terá uma descrição por descrição.
- Água e insetos. Há muita informação desnecessária e burocracia, erros e erros de digitação atrapalham a percepção. Mesmo que o leitor não seja um nazista gramatical, o descuido no texto pode desligá-lo.
Considere as dicas acima e os artigos ficarão mais claros - garantido. Para torná-lo ainda melhor, use nosso .
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 nela contidos não são corrigidos por anos. São problemas não tanto do autor, mas da organização dos processos dentro da empresa.
A documentação não acompanha o desenvolvimento
O recurso já está sendo lançado, o marketing planeja cobri-lo e então acontece que o novo artigo ou tradução ainda não está na documentação. Tivemos até que adiar o lançamento por causa disso. Você pode pedir a todos que entreguem as tarefas aos redatores técnicos no prazo que desejarem, mas isso não funcionará. Se o processo não for automatizado, a situação se repetirá.
Fizemos alterações no YouTrack. A tarefa de escrever um artigo sobre um novo recurso recai sobre o redator técnico no mesmo momento em que o recurso começa a ser testado. Então o marketing aprende sobre isso para se preparar para a promoção. As notificações também chegam ao mensageiro corporativo Mattermost, então é simplesmente impossível perder notícias dos desenvolvedores.
A documentação não reflete as solicitações do usuário
Estamos acostumados a trabalhar assim: saiu uma feature, conversamos sobre ela. Descrevemos como ligá-lo, desligá-lo e fazer ajustes finos. Mas e se um cliente usar nosso software de uma forma que não esperávamos? Ou tem erros nos quais não pensamos?
Para garantir que a documentação seja a mais completa possível, recomendamos analisar solicitações de suporte, dúvidas em fóruns temáticos e consultas em mecanismos de busca. Os tópicos mais populares serão transferidos para redatores técnicos para que possam complementar os artigos existentes ou escrever novos.
A documentação não está sendo melhorada
É difícil fazer isso perfeitamente imediatamente; ainda haverá erros. Você pode esperar feedback dos clientes, mas é improvável que eles relatem todos os erros de digitação, imprecisões, artigos incompreensíveis ou infundados. Além dos clientes, os funcionários leem a documentação, o que significa que veem os mesmos erros. Isso pode ser usado! Você só precisa criar condições nas quais seja fácil relatar um problema.
Temos um grupo no portal interno onde os colaboradores deixam comentários, sugestões e ideias sobre documentações. O suporte precisa de um artigo, mas ele não existe? O testador percebeu a imprecisão? O parceiro reclamou dos erros aos gerentes de desenvolvimento? Todos neste grupo! Os redatores técnicos consertam algumas coisas imediatamente, transferem algumas coisas para o YouTrack e dão aos outros algum tempo para pensar. Para evitar que o assunto se esgote, de vez em quando lembramos da existência do grupo e da importância do feedback.
Problema 3. Demora muito para encontrar o artigo certo.
Um artigo que não pode ser encontrado não é melhor do que um artigo que não pode ser encontrado. O lema de uma boa documentação deve ser “Fácil de pesquisar, fácil de encontrar”. Como conseguir isso?
Organize a estrutura e determine o princípio de escolha dos temas. A estrutura deve ser o mais transparente possível para que o leitor não pense: “Onde posso encontrar este artigo?” Para resumir, existem duas abordagens: a partir da interface e a partir das tarefas.
- Da interface. O conteúdo duplica as seções do painel. Este era o caso na antiga documentação do sistema ISP.
- Das tarefas. Os títulos dos artigos e seções refletem as tarefas dos usuários; Os títulos quase sempre contêm verbos e respostas à pergunta “como fazer”. Agora estamos mudando para este formato.
Qualquer que seja a abordagem escolhida, certifique-se de que o tópico seja relevante para o que os usuários estão procurando e seja abordado de uma forma que aborde especificamente a pergunta do usuário.
Configure uma pesquisa centralizada. Em um mundo ideal, a pesquisa deveria funcionar mesmo quando você digita incorretamente ou comete um erro de idioma. Nossa pesquisa no Confluence até agora não pode nos agradar com isso. Se você possui muitos produtos e a documentação é geral, adapte a pesquisa à página em que o usuário está. No nosso caso, a busca na página principal funciona para todos os produtos, e se você já estiver em uma seção específica, apenas para os artigos dela.
Adicione conteúdo e localização atual. É bom quando cada página tem um menu e uma localização atual - o caminho do usuário para a página atual com a capacidade de retornar a qualquer nível. Na antiga documentação do sistema ISP, era necessário sair do artigo para acessar o conteúdo. Era inconveniente, então consertamos no novo.
Coloque links no produto. Se as pessoas vierem ao suporte repetidamente com a mesma pergunta, faz sentido adicionar uma dica com sua solução à interface. Se você tiver dados ou informações sobre quando um usuário está enfrentando um problema, também poderá notificá-lo por meio de uma lista de e-mails. Mostre-lhes preocupação e alivie o fardo do apoio.
À direita da janela pop-up há um link para um artigo sobre como configurar DNSSEC na seção de gerenciamento de domínio do ISPmanager
Configure referências cruzadas na documentação. Artigos relacionados entre si devem ser “vinculados”. Se os artigos forem sequenciais, adicione setas para frente e para trás no final de cada texto.
Muito provavelmente, uma pessoa procurará primeiro uma resposta para sua pergunta, não para você, mas para um mecanismo de pesquisa. É uma pena se não houver links para a documentação por motivos técnicos. Portanto, cuide da otimização do mecanismo de pesquisa.
Problema 4. Layout desatualizado atrapalha a percepção
Além de textos ruins, a documentação pode ser estragada intencionalmente. As pessoas estão acostumadas a ler materiais bem escritos. Blogs, redes sociais, mídia - todo o conteúdo é apresentado não apenas bonito, mas também fácil de ler e agradável à vista. Portanto, você pode entender facilmente a dor de uma pessoa que vê um texto como na imagem abaixo.
Existem tantas capturas de tela e destaques neste artigo que elas não ajudam, apenas interferem na percepção (a imagem é clicável)
Você não deve fazer uma longa leitura da documentação com vários efeitos, mas precisa levar em consideração as regras básicas.
Disposição. Determine a largura, a fonte, o tamanho, os títulos e o preenchimento do texto do corpo. Contrate um designer e, para aceitar o trabalho ou fazê-lo você mesmo, leia o livro “Tipografia e Layout” de Artyom Gorbunov. Apresenta apenas uma visão do layout, mas é suficiente.
Alocações. Determine o que requer ênfase no texto. Normalmente, este é um caminho na interface, botões, inserções de código, arquivos de configuração, blocos “Observe”. Determine quais serão as alocações desses elementos e registre-as no regulamento. Tenha em mente que quanto menos descarga, melhor. Quando há muitos deles, o texto fica barulhento. Até as aspas criam ruído se forem usadas com muita frequência.
Screenshots. Combine com a equipe em quais casos serão necessárias capturas de tela. Definitivamente, não há necessidade de ilustrar cada etapa. Um grande número de capturas de tela, incl. botões separados interferem na percepção e prejudicam o layout. Determine o tamanho, bem como o formato dos destaques e assinaturas nas capturas de tela, e registre-os no regulamento. Lembre-se que as ilustrações devem sempre corresponder ao que está escrito e ser relevantes. Novamente, se o produto for atualizado regularmente, será difícil acompanhar todos.
Comprimento do texto. Evite artigos excessivamente longos. Divida-os em partes e, caso não seja possível, adicione conteúdo com links âncora no início do artigo. Uma maneira simples de tornar um artigo visualmente mais curto é ocultar detalhes técnicos necessários a um círculo restrito de leitores sob um spoiler.
Formatos. Combine diversos formatos em seus artigos: texto, vídeo e imagens. Isso melhorará a percepção.
Não tente encobrir problemas com um layout bonito. Honestamente, nós mesmos esperávamos que o “invólucro” salvasse a documentação desatualizada - não deu certo. Os textos continham tanto ruído visual e detalhes desnecessários que os regulamentos e o novo design eram impotentes.
Muito do que foi dito acima será determinado pela plataforma que você usa para documentação. Por exemplo, temos o Confluence. Eu tive que mexer com ele também. Se estiver interessado, leia a história do nosso desenvolvedor web: .
Por onde começar a melhorar e como sobreviver
Se a sua documentação é tão vasta quanto a do sistema ISP e você não sabe por onde começar, comece pelos maiores problemas. Os clientes não entendem o documento - melhoram os textos, fazem regulamentações, treinam redatores. A documentação está desatualizada – cuide dos processos internos. Comece com os artigos mais populares sobre os produtos mais populares: peça suporte, analise as análises do site e as consultas nos motores de busca.
Digamos imediatamente - não será fácil. E também é improvável que funcione rapidamente. A menos que você esteja apenas começando e faça a coisa certa imediatamente. Uma coisa que sabemos com certeza é que vai melhorar com o tempo. Mas o processo nunca terminará :-).
Fonte: habr.com