Como escrever um Manual do Usuário para Software

Muitas vezes cheios de jargões, acrônimos e direções que exigem um doutorado para entender, manuais de utilização de software são, por vezes escrito do ponto de vista de um desenvolvedor em vez de um usuário. Como resultado, o guia pode fazer suposições sobre o nível de habilidade do leitor que são muitas vezes incorrecta. O primeiro passo para escrever um manual de usuário boa é fazer com que o processo de escrita real, longe dos engenheiros quanto possível.

Conteúdo

Teste de usuário
O processo de entrevista
Imagens
Formatação
Controle de versão e rastreamento
referências
recursos

O desenvolvedor de software sabe mais do que ninguém o que torna o trabalho de software, mas isso não significa que o desenvolvedor deve escrever o guia. Pelo contrário, é uma desvantagem distinta. Mais importante do que uma profunda compreensão do funcionamento interno do software é uma compreensão de que o usuário final será, o que o seu nível educacional é, e como esse usuário final estará usando o software. Na maioria dos casos, os usuários finais não precisa saber os pontos mais delicados da programação e os trabalhos de back-end do software - eles só precisa saber como usá-lo para fazer seu trabalho mais fácil.

Teste de usuário
O manual do utilizador deve ser amplamente tarefa orientada, em vez de muito descritivo. Uma vez que o manual foi escrito para ajudar os usuários a entender como executar tarefas específicas, o escritor precisa ter uma compreensão dessas tarefas, bem como, e como resultado, passando por cada passo discreto de cada recurso é absolutamente essencial. Não é necessário para o escritor, necessariamente, saber como o programa foi criado a partir de um projeto ou desenvolvimento ponto de vista, mas é essencial ter um conhecimento do funcionamento de todas as suas características. Durante a execução de cada tarefa, ter tempo para escrever cada etapa, incluindo cliques, menus drop-down, e outras ações.

O processo de entrevista

Embora o desenvolvedor não deve ser o único a escrever o manual, ela ainda será um recurso valioso para o escritor, e antes de a escrita começa, planejar uma reunião inicial entre o escritor, desenvolvedor e engenheiros, e os potenciais utilizadores finais para ajudar a informar o o trabalho de escritor desde o início. Entrevistas com especialistas no assunto e engenheiros devem ser registradas, com transcrições feitas para consulta posterior.

Imagens

Um manual do usuário não deve ser muito texto pesado. Em vez disso, incorporar o uso liberal de gráficos e clipes de tela. Descrição de uma ação é muito mais clara com as direções baseadas em texto acompanhado por um clipe de tela que ilustra claramente nessa direção. Incluem tanto antes como depois vistas, para mostrar o que a tela se parece antes de tomar cada ação, eo que acontece após a ação foi tomada. Um utilitário de captura de tela simples, como a Ferramenta de Recorte incluídas no Microsoft Windows funciona bem para capturar essas imagens. Certifique-se de numerar cada imagem, e incluir uma legenda que descreve brevemente. Centrá-la imediatamente abaixo no parágrafo que primeiro introduz o conceito representado na imagem.

formatação

Comunicar-se claramente em um documento técnico exige planejamento e cumprimento rigoroso com os padrões em todo o guia. Padrões, tanto na apresentação, linguagem e ajuda nomenclatura evitar confusão. Modelos estão disponíveis e podem ser um bom ponto de partida para a uniformidade, embora estes certamente pode ser adaptado para cada situação. Usando uma margem de uma polegada com uma única coluna melhor se adapte a necessidade de adicionar gráficos- uma configuração de duas colunas pode parecer muito lotado, e pode fazer a colocação de imagens confusas.

Controle de versão e rastreamento

Mais do que qualquer outro tipo de documento, um guia de usuário do software é provável que passar por várias iterações antes de ser concluída, e é provável que passar por um processo de revisão por múltiplas partes interessadas. Usando o recurso Controlar alterações no Microsoft Word é uma maneira fácil de manter o controle dos comentários de cada indivíduo e mudanças. Criando várias versões após cada ciclo de avaliação, cada um com um nome de arquivo diferente, também ajuda o processo junto e garante que todas as partes interessadas estão satisfeitos com o resultado final.