Guia prático

Este guia foi adaptado do guia prático do The Good Docs Project. Use-o para preencher cada seção do modelo de guia prático.

Introdução

Um guia prático conduz os usuários por uma série de etapas necessárias para resolver um problema específico. Ele mostra como solucionar uma situação real ou concluir uma tarefa usando o Koha, como fechar uma biblioteca.

Nota

Uma tarefa é uma ação que os usuários podem realizar no Koha para alcançar um objetivo. A realização de um objetivo pode envolver várias tarefas.

Um guia prático descreve claramente um conjunto de etapas sequenciais para concluir uma tarefa. Ele pressupõe que o usuário tenha conhecimentos básicos do Koha.

Guias práticos são frequentemente confundidos com tutoriais. Os primeiros são orientados a tarefas, enquanto os tutoriais são orientados à aprendizagem. Veja as diferenças:

Tutorial

Guia prático

Orientado à aprendizagem: ajuda usuários iniciantes ou experientes a aprender um novo recurso de forma prática.

Orientado a tarefas: ajuda um usuário experiente a concluir uma tarefa ou solucionar um problema.

Segue um percurso cuidadosamente controlado do início ao fim.

Busca um resultado bem-sucedido e orienta o usuário pelo caminho mais seguro e confiável até o objetivo.

Elimina situações inesperadas e conduz os usuários a uma conclusão bem-sucedida.

Alerta o usuário sobre possíveis situações inesperadas e orienta como lidar com elas.

Pressupõe que os usuários não tenham conhecimentos práticos e deve indicar explicitamente todas as ferramentas, configurações de arquivos, informações conceituais etc.

Pressupõe que os usuários tenham conhecimentos práticos.

Por que preciso de um guia prático?

Um guia prático é frequentemente usado para ajudar usuários avançados a executar corretamente uma tarefa. Ele pode:

  • Demonstrar os recursos do Koha.

  • Orientar os usuários na solução de um problema real com o Koha por meio de uma série ordenada de etapas.

  • Ajudar a responder perguntas específicas dos usuários.

  • Fazer com que os usuários se sintam seguros ao usar o Koha.

  • Melhorar a experiência do usuário e ajudar a reduzir custos diminuindo o número de solicitações de suporte.

Novos usuários também podem se beneficiar de um guia prático, desde que ele seja bem escrito e indique os conhecimentos prévios necessários para concluir a tarefa.

Antes de escrever um guia prático

Antes de começar a trabalhar em um guia prático, identifique:

  • O público principal ou o caso de uso do guia.

  • As diferentes situações que os usuários podem encontrar no mundo real ao executar a tarefa. Se isto ocorrer, faça aquilo. No caso de…, uma abordagem alternativa é…

  • A forma mais segura e confiável de concluir a tarefa. Ao sugerir várias maneiras, você obriga os usuários a analisar as alternativas e escolher. Economize tempo e esforço eliminando as opções.

  • As possíveis situações que o usuário pode encontrar durante a tarefa e as soluções correspondentes.

Boas práticas para escrever um guia prático

  • Trate de um único objetivo lógico (tarefa) em cada guia. Evite casos em que apenas uma subseção seja relevante para o usuário.

  • Prepare os usuários para o inesperado: alerte-os sobre a possibilidade e explique como agir. Por exemplo, inclua destaques como aviso, cuidado ou observação para comunicar informações importantes durante a tarefa.

  • Use imperativos condicionais. Se quiser x, faça y. Para alcançar w, faça z.

  • Não explique conceitos.

  • Às vezes é útil fornecer links para documentos de apoio com mais informações, especialmente quando o usuário pode precisar de contexto ou informações conceituais e materiais de referência. No entanto, evite muitos links no guia. Mantenha os usuários na mesma página sempre que possível e coloque links para recursos adicionais no fim dela.

  • Evite documentar excessivamente várias formas de executar a mesma tarefa. Se houver mais de uma, escolha e documente o método mais comum ou recomendado. Métodos adicionais devem ser omitidos ou apenas mencionados por meio de um link ou documento de referência.

  • Certifique-se sempre de que as etapas do guia estejam tecnicamente corretas. Teste as instruções do início ao fim para identificar etapas omitidas, detalhes incorretos, etapas fora de ordem e lacunas que impeçam os usuários de avançar. Se não puder testar pessoalmente, peça a um desenvolvedor, bibliotecário ou especialista no assunto que demonstre a etapa e, se possível, grave a sessão.

  • Teste novamente as instruções após cada lançamento importante do produto para garantir que continuem corretas.

  • Guias muito longos podem sobrecarregar os usuários. Concentre-se em uma única tarefa e limite cada tarefa a no máximo 8 a 10 etapas. Se ela for grande e complexa demais, divida-a em subtarefas lógicas, cada uma com suas próprias etapas.

Sobre a seção “Visão geral”

Use esta seção para fornecer:

  • Uma descrição clara do problema ou da tarefa que o usuário pode resolver ou concluir.

  • Quando e por que o usuário pode querer executar a tarefa. Por exemplo, em um guia sobre a criação de uma solicitação de mesclagem, você pode explicar que ela é usada para informar outras pessoas sobre as alterações enviadas a um ramo do repositório.

O guia prático pressupõe que o usuário tenha conhecimentos básicos do Koha e saiba o que deseja alcançar.

Alguns exemplos:

  • Este guia explica como criar um relato no Bugzilla. Você pode criar relatos para acompanhar erros, aprimoramentos e novos recursos dos módulos e ferramentas do Koha.

  • Este guia explica como fechar temporariamente uma biblioteca. Isso pode exigir várias alterações no Koha, como informar funcionários e usuários, atualizar avisos e prorrogar datas de devolução de empréstimos.

Sobre a seção “Antes de começar”

{Esta seção é opcional}

Esta seção descreve o que os usuários precisam saber ou ter antes de seguir o guia. Ao apresentar os requisitos antecipadamente, você evita que cheguem à metade e descubram que precisam consultar outra documentação antes de prosseguir.

Use esta seção para informar os pré-requisitos do guia, como:

  • Familiaridade com o módulo ou recurso do Koha

  • Informações, programas ou ferramentas necessárias

  • Ambientes a configurar

  • Informações de autenticação e autorização

  • Outros guias ou informações a consultar

  • Links para procedimentos ou informações e orientações úteis sobre como obter o que é necessário.

Para facilitar a compreensão, considere agrupar os pré-requisitos em categorias, como conhecimentos prévios e requisitos de software.

Opcionalmente, forneça indicações de que o usuário provavelmente está no lugar errado e apresente alternativas mais adequadas. Por exemplo: se você usa Linux, consulte {link para o guia prático pertinente ao Linux}.

Exemplos:

Before you begin, ensure you have:

* A conceptual understanding of RESTful APIs.

Before you begin, ensure you have:

* API credentials for the v3.5 API.
* Access to the Postman application.
* (Optional) A development environment (IDE) that displays API responses formatted for readability.

Sobre a seção “Etapas”

A seção Etapas descreve o que o usuário precisa fazer. Use uma lista numerada para documentar as etapas do guia. O modelo as organiza desta forma:

{Task name}

{Optional: Provide a concise description of the purpose of this task. Only
include this if the purpose is not clear from the task title.}

1. {Write the action to take here. Start with a verb.}

   {Optional: Explanatory text}

   {Optional: Code sample or screenshot that helps your users complete this
   step}

   {Optional: Result}

   {Optional: If needed, you can add substeps below a primary step.}

Exemplo de etapa:

Create a pull request

Pull requests are used to inform others of changes you have pushed to a
branch in a repository. Once a pull request is opened, you can collaborate
with reviewers and make changes before merging into the base branch.

1. To create a pull request:

   1.1. Navigate to the main page of your repository.

   1.2. Under your repository name, click **Pull requests**. By default, all
   open pull requests are displayed.

Se incluir exemplos de código nas etapas, verifique também se estão recuados corretamente:

  1. Defina seu nome de usuário do Git para o repositório.

    Você pode alterar o nome associado aos commits do Git usando o comando git config.

    git config user.name "Dakota Everson"

Dicas para escrever etapas

  • Nos nomes das tarefas, comece com um verbo no infinitivo impessoal, também chamado de forma simples ou forma básica, como “conectar”, “configurar” ou “criar”, e formule o título como uma ideia completa. Não use formas nominais do verbo, pois são mais difíceis de traduzir. Em vez de “Conectar”, por exemplo, escreva “Conectar à instância da máquina virtual”.

  • Em cada etapa, você pode apresentar brevemente informações de contexto para que os usuários saibam o que farão e por quê. Continuando o exemplo, poderia indicar boas práticas para criar nomes de repositórios fáceis de lembrar.

  • Opcionalmente, acrescente um exemplo de código ou uma captura de tela depois do texto explicativo, conforme o tipo de guia. Capturas são ótimas para mostrar partes específicas da tela mencionadas na etapa. Garanta que os exemplos de código funcionem e estejam sempre atualizados.

  • Oriente os usuários ao conduzi-los por cada etapa. Se precisarem abrir um arquivo ou uma caixa de diálogo específica para concluir a tarefa, apresente primeiro essa informação.

  • Forneça exemplos de saída, como dados retornados ou uma mensagem, para que os usuários confirmem se executaram a etapa corretamente. Por exemplo, mostre como é um resultado válido e esperado após inserir um comando na interface de linha de comando.

  • Use linguagem simples e defina cada termo técnico junto à primeira ocorrência.

  • Inclua apenas uma ação em cada etapa.

Para outras dicas, consulte redação de etapas de procedimentos.

Sobre a seção “Veja também”

Ao explicar um processo com várias tarefas, é provável que você mencione outros assuntos relacionados, mas não estritamente necessários. Esta seção permite sugerir leituras adicionais sem interromper o assunto abordado no documento atual.

Um exemplo seria a configuração de um cliente de e-mail, que requer credenciais válidas de um endereço ativo. O leitor não precisa saber como instalar e executar um servidor de e-mail para obter esse acesso, embora isso possa ser útil. Portanto, o link para a documentação sobre a execução de um servidor de e-mail local poderia ser incluído na seção “Veja também”.

Recursos adicionais

Explore outros guias e modelos do The Good Docs Project.