Quais conceitos são pertinentes para planejar uma estratégia de “documentação do usuário final”?

5

Estou escrevendo muito software e sinto que escrever uma boa documentação é muito difícil. Como não conheço nenhuma teoria estruturada sobre documentação de software, comecei a organizar meus conhecimentos nesse campo e espero que isso me ajude a dividir informações em unidades sensíveis e a organizar a documentação de maneira eficiente.

Primeiro, gostaria de fazer uma lista completa de conceitos relevantes, que investigarei em outras questões.

Quais conceitos são úteis ou relevantes ao descrever a documentação do usuário? Como esses conceitos interagem entre si? Existe alguma metodologia que eu possa usar para analisar o meu software e elaborar uma estratégia de documentação pertinente?

Identifiquei os seguintes conceitos:

  • Categorias de informação como receitas (“como eu…?”), referências (como páginas man do UNIX) ou conhecimento especializado .

  • Função do usuário como usuário normal, usuário avançado, administrador do sistema e quaisquer outras funções definidas pelo sistema como agente de segurança, responsável de dados, etc.

  • Médio como um manual em papel, ajuda contextual, wiki editável.

Esses conceitos interagem um com o outro e levam a uma variedade de perguntas: Quando é útil escrever um manual para cada função? O que deve ir em cópias impressas e o que na referência on-line? Quando é útil executar um wiki reunindo “receitas”? Com esses exemplos, espero poder fornecer explicações úteis sobre o que entendo em “conceito” e “interação” em minhas perguntas.

    
por Michael Le Barbier Grünewald 03.10.2013 / 17:50
fonte

1 resposta

2

Qualquer estratégia para fornecer a documentação do usuário final será executada na seguinte lei universal da natureza:

People don't read.

Suponho que, ao se dar ao trabalho de fornecer documentação ao usuário final, você deseja fornecer um valor adicional ao cliente, na forma de um melhor entendimento sobre seu produto de software. Existem várias maneiras de fazer isso. De longe, a melhor maneira é

Write the software so that it can be understood without any documentation.

Se isso não acontecer, há várias outras estratégias que você pode empregar. O método tradicional de escrever um manual é certamente uma maneira, mas e:

  1. tutoriais em vídeo
  2. Guias de início rápido
  3. Passo a passo

Você já comprou uma peça de mobília da Ikea ou de uma dessas lojas on-line e a montou usando instruções do kit? Como foi aquela experiência? Se você fez um recentemente, você deve ter notado que ele consiste principalmente de fotos agora, com muito poucas palavras. Por quê? Porque as pessoas não lêem e, como dizem, uma imagem realmente vale mais que mil palavras.

Eu já trabalhei para uma empresa que lutou com isso. As pessoas ligariam para o suporte em vez de ler o manual. Como nós finalmente resolvemos isso? Com várias apresentações do PowerPoint que foram página após página de simplesmente andar pelo cliente em cada tela, lista suspensa e caixa de seleção. Demorou cerca de quatro meses para fazer tudo, mas nossos clientes adoraram. Eles preferiram muito mais os PowerPoints a qualquer outra forma de documentação que lhes demos.

Os tutoriais em vídeo também são bons, mas o problema é que eles são difíceis de fazer e são difíceis de usar; eles têm que ser muito curtos, porque eles não são acessíveis aleatoriamente como um manual é; você meio que tem que assistir a coisa toda. Mas eles são ótimos para obter o leigo da terra do software, por assim dizer.

Por fim, escreva um manual se precisar de um guia de referência (não como fazer). É nisso que os manuais são melhores.

    
por 25.11.2013 / 00:02
fonte