Boas referências para exemplos de documentação do usuário final e conselhos [fechado]

10

Nosso software interno foi usado por muitos usuários e o departamento de treinamento solicitou algumas dicas sobre o formato da documentação do usuário final.

Alguém sabe onde posso encontrar bons exemplos de documentação de usuário final de software que um departamento de treinamento use para inspiração ou sites com boas recomendações?

Isso é semelhante a esta pergunta, mas estou procurando documentação do usuário final para uso usado por usuários não técnicos.

design documentation users John
fonte
11
"onde posso encontrar bons exemplos de documentação do usuário final do software" Etapa 1. Compre algum software. Etapa 2. Leia a documentação. O que o impede de pegar a documentação do software existente que você já está usando? Acredito que a maioria dos pacotes de usuários finais tenha a documentação completa on-line. O que impede você de ler a documentação da Microsoft para o Office Suite?
S.Lott
Acredito que a maior parte da documentação que li foi escrita de uma maneira que não seja atraente para a leitura, e a maioria dos livros que tenho são geralmente relacionados à programação, direcionados ao público técnico. Basta ver quando alguém leu pela última vez o manual da Microsoft? Portanto, eu estava procurando alguns exemplos inspiradores.
John
Hum, q interessante.
Rook
@ John: "a maior parte da documentação". OK. Então, depois de descartar "a maioria", o que resta? Não sabemos por que você está rejeitando algumas das documentações mais usadas no planeta como "não apelando para ler". Você pode ampliar sua lista de reclamações e adicionar sua pequena lista pessoal de exemplos de documentação de software que não são excluídos pelo teste "não é interessante ler". Como não o conhecemos muito bem, não podemos adivinhar por que você quer dizer "não é atraente para ler".
S.Lott
2
Tenha cuidado para não exigir perguntas com critérios tão específicos sobre o que é "bom" que se torna localizado e não é aplicável à maioria das pessoas. Não estou interessado em esquemas de cores.
JeffO 2/11

Respostas:

1

Você pode começar entrevistando seus usuários internos sobre o software e descobrir que tipo de informação eles gostariam de saber.

Grande parte da documentação que escrevi sobre software teve em mente um ou muitos públicos. Seu departamento de treinamento provavelmente se beneficiaria de um esqueleto de tópicos (como um sumário). Então, você pode discutir quais tópicos são relevantes e quais são irrelevantes para os objetivos de treinamento.

Alguns dos tópicos podem abranger:

  1. Público alvo)
  2. Requerimentos técnicos
  3. Como instalar (se aplicável)
  4. Processo (ou seja, que função comercial o software executa?)
  5. Conjunto de recursos (que recursos o software possui?)
    • Você pode ter uma abordagem baseada em tarefas para isso, por exemplo, Adicionar um usuário ou Adicionar um documento
    • Você poderia ter uma abordagem baseada em objetos, por exemplo, Usuários, Funções
    • Você pode ter uma abordagem baseada em menus, por exemplo, menu Arquivo, Exibir menu
  6. Por fim, possivelmente uma seção Próximos recursos e Perguntas frequentes pode atuar como um crescente repositório de conhecimento do seu produto.

Tente antecipar como seus usuários finais usam seu software, com base no seu conhecimento de desenvolvê-lo, no seu conhecimento do que ele faz e também com base (espero) em suas entrevistas com os usuários finais.

Mais importante, tente criar a documentação que você gostaria de ler, use nomes de exemplo divertidos para demonstrar e use muitas capturas de tela anotadas.

Espero que isto ajude

funkymushroom
fonte
2

Eu li vários "Guias do usuário final" e escrevi um, e acho que existem muitos elementos que melhoram sua eficácia:

  • Mostre com imagens como é emitido algum comando ou feito alguma ação (capturas de tela por exemplo).
  • Concentre-se na necessidade de fazer algo e na maneira de fazê-lo. Fique longe de descrições técnicas sobre quão otimizada é essa ação realizada, por exemplo.
  • Depois de colocar um fluxograma descrevendo os módulos, o software foi dividido e recebi comentários de que não era muito útil.
  • Tente prever os possíveis problemas que um usuário possa ter, para que a seção Solução de problemas seja útil. Você também deve testar seu programa com usuários que não estavam envolvidos no seu desenvolvimento, até mesmo com colegas de trabalho que participaram de outros projetos.
  • Evite descrições chatas. Qualquer informação adicional pode ser colocada em um apêndice ou algo parecido.

Espero que isso possa ser útil para você.

Nicolás
fonte
1

Você mencionou que será usado para treinamento.

Se você está procurando um documento de treinamento em vez de um documento de referência, meu site favorito é o tutorial de Joel Spolsky sobre Mercurial aqui .

  1. Apresentação simples e limpa. É bom olhar.
  2. Autoritário, mas pessoal em tom. Parece que você está em uma ótima palestra na faculdade.
  3. Fotos simples, não copiosa quantidade de capturas de tela reais. Leia A parte de trás do guardanapo para saber por que isso funciona.

Se você está treinando um documento com metade do legal do tutorial de Joel, eu li. Mas você precisa de alguém com a) uma paixão pela escrita eb) uma incrível profundidade de conhecimento para obtê-la, mesmo que você possa copiar os 3 pontos acima. Espero que funcione.

MikeRand
fonte
0

Não sei se isso possivelmente atende às suas necessidades, mas existem sistemas usados ​​para a documentação técnica da esfinge, sendo um que vem à mente que facilita a criação de uma documentação on-line. Algo assim poderia ser usado para o que você está interessado?

Também encontrei o ReadTheDocs, que faz a mesma coisa, mas é uma solução hospedada.

Piper Merriam
fonte
0

Confira a Sociedade de Comunicação Técnica (STC) . Muitos de seus vencedores escreveram uma produção geralmente disponível. Eles também podem ter amostras disponíveis. Tornar-se um membro também fornecerá acesso a um corpo maior de informações.

Jim Rush
fonte