50 perguntas para trabalhar na documentação

Não importa o quanto o designer UX tente, uma pessoa da rua não será capaz de descobrir a interface de controle da espaçonave sem uma dica. E nem mesmo da rua. Só porque o foguete é grande e há muitas configurações.

Tornamos os produtos mais simples que o software para foguetes, mas ainda tecnicamente sofisticados. Nós nos esforçamos muito para que as interfaces das novas versões sejam simples, mas percebemos que sempre haverá um usuário que não entenderá algo e irá para a documentação. Portanto, deve haver uma doca e, para não estragar a impressão do produto, deve ser útil e conveniente.

Temos seis produtos, cuja documentação foi elaborada pelos desenvolvedores desde a fundação da empresa. Por meio ano, reescrevemos artigos antigos e escrevemos novos . Sob o corte - 50 perguntas que nos ajudam a fazer isso bem. Mas, para começar, um pouco introdutório.

Por que a documentação é importante e quem deve fazê-lo

Fazer uma boa doca é difícil. Em algum lugar, um grande departamento de analistas, escritores e editores está trabalhando nele, e em algum lugar os desenvolvedores estão escrevendo no dock (pronto - descrito).

Temos dois escritores técnicos em seis produtos com várias versões. Isso não é suficiente; portanto, gerentes de produto, testadores, a primeira linha de suporte e marketing trabalham no banco dos réus. Eles não escrevem artigos, mas ajudam a entender o produto e as tarefas do cliente, escolher um tópico e coletar informações, verificar o conteúdo e o design do artigo final. Juntos, melhoramos a doca.

Se você possui um pequeno departamento de redatores de tecnologia, recrute funcionários de outros departamentos. Se eles não estiverem interessados, dê argumentos da lista abaixo. Primeiro suporte, segundo e terceiro marketing e marketing de produto. Então, por que a documentação é importante?

1. Fator de suporte . A primeira e mais óbvia das razões. Se a documentação estiver boa, a maioria dos clientes resolverá o problema sem entrar em contato com o suporte. O suporte restante lançará um link para as instruções ou passará por ele rapidamente. Documentação completa pode ser usada para criar bots de bate-papo. Tudo isso reduz o tempo de resposta aos clientes, aumenta sua satisfação e também reduz os custos de suporte.
2. Fator de seleção . A documentação afeta a escolha do cliente, além do preço, conveniência e funcionalidade. Isso é confirmado por nossa pesquisa e feedback dos usuários do ISPmanager e DCImanager . Nesse sentido, a doca deixa de ser uma necessidade de suporte, mas se torna uma vantagem competitiva, parte do marketing.
3. Fator de lealdade . Se o cliente saiu sem entender o encaixe no início ou no processo, isso é um problema. Atrair um cliente é muito caro para perder devido a artigos ruins.

Como fazer uma boa documentação

Defina uma meta . Esta é a maior dor. Descrever um recurso apenas para fins de descrição ou comentário em uma interface não é o objetivo. Um objetivo é sempre uma ação benéfica. O que um usuário, administrador ou desenvolvedor deve saber e poder ler depois de ler um artigo? Por exemplo, crie um site e vincule um domínio a ele, emita um certificado SSL, configure backups, etc. Ou seja, resolva seu problema.

Conheça o público . Dividimos os clientes em usuários, administradores e desenvolvedores. Mas isso não é suficiente para criar textos úteis. Para entender rapidamente o público, você pode acessar o UX e o produto, estudar solicitações de suporte e suas respostas sobre o tópico, ouvir chamadas de primeira linha, consultar o site e o blog (o marketing também escreve as coisas necessárias). E somente depois disso comece a escrever.

Verifique, edite e verifique novamente . Os escritores técnicos devem fazer uma verificação inicial. Depois dela mais uma. Vale a pena conectar o suporte, o marketing e outros departamentos à auditoria. Então você precisa verificar com o manual de estilo e design - política editorial. Alguém do lado ou outro escritor de tecnologia o deixou fazer a revisão final. Se você tem um editor, ele assumirá esse estágio.

Distribua o artigo após a publicação . Se a documentação estiver escrita, provavelmente alguém precisará dela. Mostre-o à luz e use-o ao máximo: traduza, consulte o produto, dê-o a marketing, suporte. Não escreva para a mesa.

50 perguntas para trabalhar na doca

Trabalhando na documentação, repetimos os mesmos erros. Eles passaram muito tempo checando os artigos, e o guia, que inicialmente parecia uma panacéia, não ajudou, porque o problema estava na abordagem e no conteúdo. Para que os redatores técnicos pudessem trazer o artigo à mente de maneira rápida e rápida, reunimos em uma lista todas as perguntas que constantemente fizemos (ou esquecemos de fazer). Use se estiver escrevendo uma dock também.

Objetivos

1. Para quem estou escrevendo um artigo? Quem é o futuro leitor: usuário, administrador, desenvolvedor?
2. Que tarefas ele enfrenta (trabalhos a serem realizados)? Existe uma descrição da pessoa?
3. Qual é o nível de treinamento deste usuário? O que ele já sabe? O que não é óbvio para ele?
4. Como posso explicar isso para um usuário iniciante e, ao mesmo tempo, não irritar a explicação avançada das coisas básicas?
5. O que mais precisa ser explicado ao usuário para que ele entenda o conteúdo principal do artigo?
6. Para que seção da documentação este artigo é adequado?
7. Este artigo ou parte dele deve ser duplicado em outras seções?
8. Quais artigos devo vincular?
9. Talvez este artigo deva ser acompanhado por uma instrução em vídeo?

Fontes de informação

10. Os usuários atuais têm problemas com o tópico do artigo?
11. Como o suporte agora explica o que precisa ser feito?
12. O departamento de marketing escreveu artigos e notícias sobre este tópico? Eles podem "espionar" suas palavras, estrutura etc.?
13. Há alguma seção sobre esse tópico no site?
14. O que o script incluiu o UX e o gerente de produto? Por que fez isso?
15. Como essa pergunta é descrita pelos concorrentes?
16. Em que áreas você ainda pode ver as melhores práticas?

Verificação de conteúdo

17. Você alcançou o objetivo do artigo?
18. Tudo ficará claro para um usuário mais avançado?
19. Tudo ficará claro para um usuário iniciante?
20. Tudo é lógico e consistente? Sem saltos e abismos?
21. A sequência de ações está correta? O usuário poderá atingir a meta seguindo apenas esta instrução?
22. Levamos em consideração todos os casos / caminhos do usuário?
23. O artigo se encaixa na seção selecionada?

Verificação de layout

24. Existem folhas de texto ilegíveis? É possível substituir o circuito?
25. Existem parágrafos longos?
26. Existem parágrafos curtos?
27. Existem listas muito longas?
28. Existem listas muito complicadas para a percepção (aquelas em que existem mais de dois ou três níveis)?
29. Existem imagens suficientes?
30. Não há muitas imagens? Estamos ilustrando etapas óbvias demais?
31. Se existem esquemas, eles são compreensíveis?
32. As tabelas não são difíceis de serem percebidas?
33. A página em geral parece boa?

Edição Literária

34. Tudo foi projetado de acordo com o guia?
35. O estilo do restante da documentação é consistente?
36. Alguma sugestão que pode ser simplificada?
37. Existem termos complexos que precisam de esclarecimentos?
38. Existe um clericalismo?
39. Existe uma repetição?
40. Nada prejudica sua audição?

Revisão final

41. Existem erros de digitação, ortografia ou pontuação?
42. Hífens, parágrafos e seções estão bem?
43. Todas as imagens estão assinadas?
44. Os elementos da interface estão nomeados corretamente?
45. Existem links em todos os lugares? Eles trabalham e para onde vão?

Imediatamente após a publicação

46. ​​O artigo possui seções que são "puxadas" para outros artigos? Eles são decorados com macros para que as alterações em um artigo sejam aplicadas automaticamente a outros?
47. Este artigo deve ser referenciado em outras seções? Se sim, de qual?
48. Precisa adicionar um link rápido para este artigo no produto?
49. Tenho que enviar o link para suporte, marketing ou outros departamentos?
50. Tenho que enviar um artigo para tradução?

Esta lista pode ser impressa e colocada na mesa ou pendurada na parede. Ou transforme-se em uma lista de verificação. Algumas das perguntas podem ser trazidas para o processo comercial. A nossa, por exemplo, é corrigida no processo geral de desenvolvimento no YouTrack. A tarefa de documentação passa por diferentes estágios e departamentos, sem documentação escrita, você não pode fornecer um recurso para liberar.