Guia prático

Este guia foi adaptado do guia de instruções do The Good Docs Project. Utilize este guia para preencher cada secção do modelo de instruções.

Introdução

Um guia de instruções conduz os utilizadores através de uma série de passos necessários para resolver um problema específico. Mostra como resolver um problema do mundo real ou realizar uma tarefa utilizando o Koha, como, por exemplo, como terminar as atividades de uma biblioteca.

Nota

Uma tarefa é uma ação que os seus utilizadores podem realizar no Koha para atingir um objetivo. Várias tarefas podem estar envolvidas na concretização de um objetivo.

Um guia de instruções descreve claramente uma série de passos sequenciais para realizar uma tarefa. O guia pressupõe que o utilizador possui conhecimentos básicos sobre o Koha.

Os guias de instruções são frequentemente confundidos com tutoriais. Os guias de instruções são orientados para tarefas, enquanto os tutoriais são orientados para a aprendizagem. As diferenças entre os dois:

Tutorial

Guia

Orientado para a aprendizagem: ajuda os principiantes ou utilizadores experientes a aprender uma nova funcionalidade de forma prática.

Orientado para tarefas: ajuda um utilizador especialista a realizar uma tarefa ou a resolver um problema.

Segue um caminho cuidadosamente gerido, do início ao fim.

Visa um resultado bem-sucedido e orienta o utilizador pelo caminho mais seguro e garantido até ao objetivo.

Elimina quaisquer cenários inesperados e proporciona aos utilizadores um desfecho bem-sucedido.

Alerta o utilizador para a possibilidade de cenários inesperados e orienta sobre como lidar com os mesmos.

Parte do princípio de que os utilizadores não possuem conhecimentos práticos e exige que sejam explicitamente indicadas quaisquer ferramentas, configurações de ficheiros, detalhes conceptuais, entre outros.

Pressupõe que os utilizadores possuam conhecimentos práticos.

Porque preciso de um guia de instruções?

Um guia de instruções é frequentemente utilizado para ajudar os utilizadores avançados a realizar uma tarefa corretamente. Ele pode:

  • Demonstrar as capacidades do Koha.

  • Orientar os seus utilizadores para resolver um problema do mundo real com o Koha através de uma sequência ordenada de passos.

  • Ajudar a responder a perguntas específicas que os utilizadores possam ter.

  • Fazer com que os utilizadores se sintam à vontade ao utilizar o Koha.

  • Melhorar a experiência do utilizador e ajude a reduzir os custos, diminuindo o número de pedidos de suporte.

Os novos utilizadores também podem beneficiar de um guia de instruções, desde que este esteja bem escrito e indique qualquer conhecimento prévio necessário para realizar a tarefa.

Antes de escrever um guia de instruções

Antes de começar a elaborar um guia de instruções, identifique:

  • O público-alvo ou caso de utilização principal do guia.

  • Os diferentes cenários que os utilizadores podem encontrar no mundo real ao realizar uma tarefa. Se isto, então aquilo. No caso de…, uma abordagem alternativa é…

  • A forma mais garantida e segura de realizar uma tarefa. Ao sugerir várias formas de completar uma tarefa, pede aos utilizadores que analisem as diferentes opções e façam uma escolha. Poupe o tempo e o esforço dos seus utilizadores eliminando estas opções.

  • Os cenários possíveis que um utilizador pode encontrar ao realizar uma tarefa, e as soluções correspondentes.

Melhores práticas para escrever um guia de instruções

  • Aborde um objetivo lógico (tarefa) para cada guia de instruções. Tente evitar situações em que apenas uma subsecção do guia é relevante para o utilizador.

  • Prepare os seus utilizadores para o inesperado, alerte-os para esta possibilidade e forneça orientações sobre como lidar com a situação. Por exemplo, utilize elementos de destaque, como avisos, alertas ou notas, para transmitir informações importantes durante a realização de uma tarefa.

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

  • Não explique conceitos.

  • Por vezes, é útil fornecer ligações para documentação de suporte que ofereça mais informação, especialmente quando o utilizador pode necessitar de contexto ou informação conceptual e materiais de referência. No entanto, evite incluir endereços em excesso no guia de instruções. Mantenha os utilizadores numa única página sempre que possível e disponibilize endereços para recursos adicionais no final da página.

  • Evite documentar excessivamente múltiplas formas de realizar a mesma tarefa. Se existir mais do que uma forma de completar uma determinada tarefa, escolha e documente o método mais comum ou recomendado. Os métodos adicionais devem ser omitidos ou mencionados através de um link ou documento de referência.

  • Certifique-se sempre de que os passos apresentados no seu guia de instruções são tecnicamente precisos. Teste as suas instruções do início ao fim para identificar passos omitidos, detalhes incorretos, passos fora de ordem e lacunas de informação que possam impedir o progresso dos utilizadores. Caso não seja possível realizar o teste pessoalmente, peça a um programador, bibliotecário ou especialista no assunto que lhe demonstre o procedimento e, se possível, grave a sessão.

  • Reavalie as instruções após cada lançamento importante de produto para garantir que se mantêm precisas.

  • Guias de instruções demasiado longos podem sobrecarregar os utilizadores. Concentre-se apenas numa tarefa por separador e limite-o a um máximo de 8 a 10 passos por tarefa. Se a tarefa for muito extensa e complexa, divida-a em várias subtarefas lógicas, cada uma com os seus próprios passos.

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

Utilize esta secção para fornecer:

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

  • Quando e por que razão o utilizador pode querer realizar a tarefa. Por exemplo, num guia sobre como criar um pull request, pode explicar aos utilizadores que os pull requests servem para informar outras pessoas sobre as alterações enviadas para uma branch num repositório.

O guia pressupõe que o utilizador tem conhecimentos básicos do Koha e sabe o que pretende alcançar.

Alguns exemplos:

  • Este guia explica como criar um issue no Bugzilla. Pode criar issues para acompanhar bugs, melhorias e novas funcionalidades para os módulos e ferramentas do Koha.

  • Este guia explica como fechar temporariamente uma biblioteca. O encerramento temporário de uma biblioteca pode exigir a realização de várias alterações no Koha, tais como informar o pessoal e os leitores, atualizar os avisos e prorrogar as datas de devolução dos empréstimos.

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

{Esta secção é opcional}

Esta secção descreve o que os seus utilizadores precisam de saber ou ter à mão antes de iniciar o procedimento. Ao apresentar os requisitos logo de início, evita que estes cheguem a metade do processo e descubram que têm de ler outra documentação antes de avançar.

Utilize esta secção para informar quaisquer pré-requisitos para este guia, tais como:

  • Familiaridade com um módulo ou funcionalidade do Koha

  • Quaisquer informações, software ou ferramentas necessárias

  • Ambientes para configurar e definir

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

  • Outros guias ou informações para ler

  • Links para procedimentos ou informações, ou quaisquer orientações úteis sobre como obter o que precisam.

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

Opcionalmente, forneça indicações que sinalizem ao utilizador que está provavelmente no local errado e ofereça opções mais adequadas. Por exemplo, se for utilizador de Linux, consulte {endereço para o guia de instruções relevante para 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 secção “Passos”

A secção de passos é onde descreve o que o utilizador precisa de fazer. Utilize uma lista numerada para documentar o passo a passo. O modelo organiza as etapas 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.}

Um exemplo de um passo:

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 estiver a incluir exemplos de código nos seus passos, certifique-se de que também estão corretamente indentados:

  1. Defina o seu nome de utilizador Git para o seu repositório.

    Pode alterar o nome associado aos seus commits do Git utilizando o comando git config.

    git config user.name "Dakota Everson"

Dicas para escrever passos

  • Para os nomes das tarefas, comece com um verbo no infinitivo simples (também conhecido como forma básica). Por exemplo: “conectar”, “configurar” ou “construir”, e exprima o título como um pensamento completo. Não utilize a forma do verbo com “-indo”, pois é mais difícil de traduzir. Em vez de apenas “Conectar”, pode dizer “Conectar à máquina virtual”.

  • Para cada passo, forneça, opcionalmente, algumas informações de contexto sobre a tarefa, para que os utilizadores saibam o que estão prestes a fazer e porquê. Continuando com o exemplo, pode apresentar algumas boas práticas para criar nomes de repositórios memoráveis.

  • Opcionalmente, adicione um exemplo de código ou uma captura de ecrã após o texto explicativo, dependendo do tipo de guia de instruções que está a escrever. As capturas de ecrã são uma ótima maneira de mostrar partes específicas do ecrã às quais se refere num só passo. Certifique-se de que os seus exemplos de código funcionam e estão sempre atualizados.

  • Lembre-se de orientar os utilizadores ao guiá-los por cada passo. Se precisarem de abrir um ficheiro ou caixa de diálogo específica para completar a tarefa, forneça primeiro essa informação.

  • Forneça exemplos de saída, como dados de retorno ou uma mensagem, para que os utilizadores possam validar se executaram o passo corretamente. Por exemplo, pode querer mostrar qual é o resultado válido e esperado ao introduzir um comando numa CLI.

  • Utilize uma linguagem simples e defina qualquer termo técnico logo de seguida.

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

Para obter dicas adicionais sobre como escrever passos, consulte escrever passos procedimentais.

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

Ao explicar um processo com várias tarefas, é provável que mencione outros tópicos relacionados com o assunto em questão, mas que não sejam estritamente necessários. Esta secção é útil para oferecer aos utilizadores sugestões de leitura complementar, sem interromper o tema abordado no documento atual.

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

Recursos adicionais

Explore outros guias e modelos do The Good Docs Project.