A documentação do software é apenas uma coleção de artigos, mas mesmo eles podem deixá-lo louco. Primeiro, você procura as instruções corretas por um longo tempo, depois entende o texto obscuro, faz o que está escrito, mas o problema não está resolvido. Você está procurando outro artigo, está nervoso ... Depois de uma hora, cuspe em tudo e sai. É assim que a documentação ruim funciona. O que o torna assim e como corrigi-lo - leia abaixo do corte.
Nossa documentação antiga tinha muitas falhas. Já faz quase um ano que o processamos para que o cenário descrito acima não diga respeito aos nossos clientes. Veja como foi e como se tornou .
Problema 1. Artigos incompreensíveis e mal escritos
Se é impossível descobrir a documentação, qual é o sentido? Mas ninguém escreve artigos obscuros de propósito. São obtidas quando o autor não pensa na audiência e no objetivo, derrama água e não verifica se há erros no texto.
- A audiência . Antes de escrever um artigo, você precisa pensar no nível de preparação do leitor. É lógico que, no artigo para iniciantes, você não deve pular as etapas básicas e deixar os termos técnicos sem descriptografia, e no artigo sobre um recurso raro que é necessário apenas para os profissionais, analise o significado da palavra PHP.
- Objetivo . Outra coisa que você deve pensar antes. O autor deve definir uma meta clara, determinar o efeito útil do artigo, decidir o que o leitor fará depois de lê-lo. Se isso não for feito, uma descrição será obtida por uma questão de descrição.
- Água e insetos . Muita informação desnecessária e clericalismo, erros e erros de digitação interferem na percepção. Mesmo que o leitor não seja uma nação gramatical, a negligência no texto pode afastá-lo.
Considere as dicas acima e os artigos ficarão mais claros - garantidos. Para melhorar ainda mais, faça nossas
50 perguntas ao trabalhar na documentação técnica .
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, os erros não são corrigidos há 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
O recurso já está no lançamento, planeja cobri-lo e o novo artigo ou tradução ainda não está na documentação. Por isso, tivemos que adiar o lançamento. Você pode pedir a todos que entreguem a tarefa aos escritores técnicos a tempo, mas isso não funcionará. Se o processo não for automatizado, a situação será repetida.
Fizemos alterações no YouTrack. A tarefa de escrever um artigo sobre um novo recurso recai sobre o redator técnico no momento em que ele começa a testar a oportunidade. Em seguida, o marketing aprende sobre ela para se preparar para a promoção. As notificações também vêm no messenger corporativo Mattermost, por isso é simplesmente impossível perder as notícias dos desenvolvedores.
A documentação não reflete solicitações do usuário
Nós costumávamos trabalhar assim: um recurso saiu, conversamos sobre isso. Descrevemos como ativá-lo, desativá-lo, fazer ajustes finos. Mas e se o cliente usar nosso software de uma maneira que não esperávamos? Ou ele está cometendo erros nos quais não pensamos?
Para que a documentação seja o mais completa possível, recomendamos que você analise solicitações de suporte, perguntas em fóruns temáticos e consultas nos mecanismos de pesquisa. Os tópicos mais populares devem ser repassados aos escritores técnicos para complementar os artigos existentes ou escrever novos.
A documentação não está sendo aprimorada
É difícil fazer isso imediatamente, de qualquer maneira, haverá erros. Você pode confiar nos comentários dos clientes, mas é improvável que eles relatem todos os artigos sobre erros de digitação, imprecisão, incompreensibilidade ou desconhecido. Além dos clientes, os funcionários leem a documentação, o que significa que eles veem os mesmos erros. Pode ser usado! Só é necessário criar condições nas quais será fácil relatar um problema.
Temos um grupo no portal interno onde os funcionários deixam comentários, sugestões e idéias na documentação. O suporte precisa de um artigo, mas não? O testador notou uma imprecisão? Parceiro reclamou com os gerentes de desenvolvimento sobre erros? Tudo neste grupo! Os escritores técnicos corrigem algo imediatamente, transferem algo para o YouTrack, levam algo para pensar. Para manter o tópico quieto, lembramos de tempos em tempos a existência do grupo e a importância do feedback.
Problema 3. Você precisa procurar o artigo certo por um longo tempo
Um artigo que não pode ser encontrado não é melhor do que um artigo que não é. O lema da boa documentação deve ser "Fácil de pesquisar, fácil de encontrar". Como conseguir isso?
Simplifique a estrutura e determine o princípio de escolher tópicos . 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: na interface e nas tarefas.
- A partir da interface. O conteúdo duplica seções do painel. Assim estava na documentação antiga do ISPsystem.
- De 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 para a pergunta "como fazer". Agora estamos nos movendo para esse formato.
Seja qual for a abordagem escolhida, verifique se o tópico atende às necessidades dos usuários e é coberto para que o usuário resolva com precisão sua pergunta.
Estabeleça uma pesquisa centralizada . Em um mundo ideal, a pesquisa deve funcionar mesmo quando você está triste ou se engana com o idioma. Nossa pesquisa em Confluence ainda não pode agradar. Se você tiver muitos produtos e a documentação for geral, adapte a pesquisa à página em que o usuário está localizado. No nosso caso, a pesquisa principal funciona em todos os produtos e, se você já estiver em uma seção específica, apenas nos artigos nela.
Adicione conteúdo e trilhas de navegação . É bom quando há um menu e trilhas de navegação em cada página - o caminho do usuário para a página atual com a capacidade de retornar a qualquer nível. Na documentação antiga do ISPsystem, você precisava sair do artigo para entrar no conteúdo. Era inconveniente, então no novo nós o corrigimos.
Organize os links no produto . Se, ocasionalmente, as pessoas fornecerem suporte para a mesma pergunta, é razoável adicionar uma dica com sua solução à interface. Se você tiver dados ou entender em que momento o usuário se depara com um problema, também poderá notificá-lo por boletim informativo. Tome cuidado e remova a carga do suporte.
À direita na janela pop-up, há um link para um artigo sobre a configuração do DNSSEC na seção de gerenciamento de domínio do ISPmanagerConfigure referências cruzadas na documentação . Os artigos relacionados devem ser "vinculados". Se os artigos forem uma sequência, adicione setas para frente e para trás no final de cada texto.
Provavelmente, uma pessoa primeiro procurará 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. O layout desatualizado interfere na percepção
Além de textos incorretos, o design pode estragar a documentação. As pessoas estão acostumadas a ler materiais bem feitos. Blogs, redes sociais, mídia - todo o conteúdo é apresentado não apenas bonito, mas também fácil de ler, agradável aos olhos. Portanto, você pode entender facilmente a dor de uma pessoa que vê o texto como na imagem abaixo.
Há tantas capturas de tela e seleções neste artigo que elas não ajudam, mas apenas interferem na percepção (a imagem é clicável)Não vale a pena fazer uma pausa com vários efeitos da documentação, mas você precisa considerar as regras básicas.
Layout . Defina a largura do texto principal, fonte, tamanho, cabeçalhos e recuos. Envolva um designer e, para aceitar um trabalho ou faça você mesmo, leia o livro Typography and Layout, de Artyom Gorbunov. Apresenta apenas uma das visualizações no layout, mas é o suficiente.
Alocações . Defina o que precisa ser enfatizado no texto. Normalmente, esse é o caminho na interface, botões, inserções de código, arquivos de configuração, blocos “Preste atenção”. Defina qual será a seleção desses elementos e corrija na programação. Lembre-se de que quanto menos excreção, melhor. Quando existem muitos deles, o texto "faz barulho". Até aspas criam ruído se usadas com muita frequência.
Screenshots Organize com a equipe quais são as capturas de tela dos casos. Definitivamente, não há necessidade de ilustrar cada etapa. Um grande número de capturas de tela, incluindo botões individuais interferem na percepção, estragam o layout. Determine o tamanho, bem como o formato das seleções e legendas nas capturas de tela, corrigidos nos regulamentos. Lembre-se de que as ilustrações devem sempre ser escritas e relevantes. Novamente, se o produto for atualizado regularmente, será difícil acompanhar cada um deles.
O comprimento do texto . Evite artigos excessivamente longos. Fragmente-os em partes e, se não for possível, adicione conteúdo vinculado à âncora na parte superior do artigo. Uma maneira fácil de tornar um artigo visualmente mais curto é ocultar os detalhes técnicos necessários para um círculo estreito de leitores sob um spoiler.
Formatos Combine vários formatos em artigos: texto, vídeo e imagens. Isso irá melhorar a percepção.
Não tente encobrir problemas com um layout bonito. Honestamente, esperávamos que o "wrapper" salvasse a documentação desatualizada - não deu certo. Os textos tinham tanto ruído visual e detalhes desnecessários que os regulamentos e o novo design eram impotentes.
Grande parte do exposto acima será determinada pelo site que você usa para documentação. Para nós, por exemplo, isso é Confluence. Ele também teve que mexer com. Se estiver interessado, leia a história de nosso desenvolvedor da Web:
Confluence para uma base de conhecimento pública: altere o design e configure a separação de idiomas .
Onde começar a melhorar e como sobreviver
Se sua documentação é tão vasta quanto a do ISPsystem e você não sabe o que pegar, comece pelos problemas mais sérios. Os clientes não entendem como melhorar textos, elaborar regulamentos e treinar escritores. A documentação está desatualizada - assuma processos internos. Comece com os artigos mais populares sobre os produtos mais procurados: solicite suporte, consulte análises de sites e consultas de mecanismos de pesquisa.
Digamos imediatamente - não será fácil. E rapidamente, também, é improvável que tenha sucesso. A menos que você esteja começando e fazendo imediatamente. Sabemos uma coisa com certeza: ela ficará melhor com o tempo. Mas o processo nunca termina :-).