User Documentation Neste tutorial pode aprender como fazer um tutorial.
Um tutorial é uma lição que o guia através de uma série de passos práticos. Oferece uma experiência de aprendizagem ao fazer algo. É a melhor forma de conhecer um assunto com o qual ainda não está familiarizado. Os tutoriais são cruciais em qualquer documentação: mostram aos recém-chegados o essencial, guiam os primeiros passos, são a montra, dão uma experiência agradável e fácil de um tópico. Um dos "truques" para conseguir isto é deixar de fora tudo o que possa distrair no processo de aprendizagem. Por exemplo:
- Formas alternativas de fazer algo ou formas de fazer algo muito específico.
- Referências completas de todas as opções e uma descrição técnica da sua estrutura.
- Explicações detalhadas e antecedentes históricos.
Essa informação extra pode ser melhor fornecida separadamente. Evite ao máximo misturá-la, pois isso apenas tornará o tutorial confuso. Este é o princípio principal do Framework Diátaxis, uma forma sistemática de melhorar a documentação. Coloque a informação extra acima mencionada em guias práticos, referências e explicações respetivas. Nos guias práticos pode encontrar rapidamente como fazer algo específico. Nas referências pode consultar como funcionam as coisas, que opções têm e onde encontrar mais informação. Com explicações pode aprofundar a sua compreensão do tópico.
Embora um tutorial ofereça uma introdução a um tópico, não se destina exclusivamente a principiantes. Pode também ser uma introdução a um tópico avançado! Seja claro no início do seu tutorial sobre que conhecimento ou habilidade é necessário para poder realizar o tutorial.
Se ensinar alguém a cozinhar, tem de explicar coisas como técnicas de corte, como usar um forno e outras noções básicas de cozinha. Comece com uma receita simples, de preferência algo que facilmente resulte num bom produto final. Esse produto final em si não é o objetivo principal: quer ensinar algumas competências. É isto que um tutorial faz. Alguém que já saiba cozinhar e queira fazer algo específico não precisa de um tutorial assim, mas sim de uma receita. As receitas são os guias práticos da culinária.
Passo a passo
Para criar um tutorial:
- Reúna informações sobre o tópico. Documentação existente, vídeos, etc. Anote as coisas que achou confusas ou que lhe demoraram algum tempo a compreender. Existem perguntas sobre o assunto no fórum?
- Que conceitos estão envolvidos? Rabiscar um pequeno diagrama pode ajudar. Não tente ser completo, mas deixe claro o que é importante para este tutorial e o que não é.
- Existe algum conhecimento ou competência específicos que sejam necessários ensinar no seu tutorial?
- Crie um exemplo no qual possa usar todos os conceitos e competências que deseja transmitir no tutorial. Torne o exemplo o mais simples possível.
- Defina e escreva passos para chegar a um resultado final. Cada passo deve ser reproduzível pelo seu aluno.
- Filtre todas as explicações, referências, alternativas e casos especiais; coloque-os em artigos separados.
- Escreva uma introdução. O que vai aprender neste tutorial? Mencione quaisquer pré-requisitos necessários para fazer o tutorial.
- Escreva o resumo. O que aprendemos? Também pode mencionar quais os próximos passos a dar para aprender mais.
- Adicione capturas de ecrã com anotações para ilustrar as ações a tomar. Dica: use números na captura de ecrã e dê explicações no texto. Isso facilita a reutilização da sua captura de ecrã em traduções e minimiza o esforço de produzir capturas de ecrã específicas de cada idioma.
- Adicione diagramas para explicar estruturas, relações e processos.
- Adicione os artigos que acompanham com explicações, referências e guias práticos.
- Coloque todos os artigos de um assunto sob um artigo de visão geral, explicando o que é cada coisa, como se relacionam e por onde começar.
Exemplo — criar e publicar um artigo no Joomla
Como exemplo, vamos criar um tutorial sobre como criar e publicar um artigo sob um item de menu no Joomla.
Recolha de informações
No nosso manual do utilizador encontrará artigos relevantes em "Introdução", "Artigos" e "Menus". É frequentemente confuso, quando se começa a usar o Joomla, não ver um artigo depois de o ter criado, mesmo tendo-o marcado como "publicado". Para ver o artigo, tem de existir uma hiperligação para ele. Existem várias formas de criar essa hiperligação (como um item de menu ou um esquema de blogue de categoria ou colocando-o no esquema de blogue da página inicial marcando o artigo como destacado ou criando uma hiperligação a partir de outro artigo), mas vamo-nos agora concentrar em disponibilizar o artigo através de um item de menu.
Conceitos e competências
Temos 'conteúdo', 'artigo', 'menu' e 'item de menu'. Temos de clarificar esses termos. Mostramos onde encontrar essas coisas no menu de administração. Deixamos de fora 'categorias' ou 'destacado' neste tutorial.
Pré-requisitos
Tem de ter acesso à área administrativa de um sítio Joomla em funcionamento e saber como fazer autenticação.
Objetivo
O nosso objetivo é aprender como criar um novo artigo Joomla e um novo item de menu sob o qual colocamos o nosso artigo.
Passos
Siga os passos seguintes para alcançar o nosso objetivo:
A. Criar um artigo
- Faça autenticação no painel de administração do Joomla.
- Primeiro vamos criar o artigo. Navegue até ao menu "Conteúdo" à esquerda e selecione "Artigos".
- Clique em "Novo" para criar um novo artigo.
- Introduza um título e conteúdo para o seu artigo.
- Clique em "Guardar e fechar" para guardar o seu artigo.
B. Criar um item de menu com hiperligação para o artigo
para mostrar o artigo no sítio vamos criar um item de menu com hiperligação para o artigo. Navegue até ao menu "Menus" à esquerda e selecione "Menu principal".
- Tal como com um artigo, clique em "Novo" para criar um novo item de menu.
- Introduza um título para o seu item de menu. Este é o título tal como aparecerá no menu. Não tem de ser igual ao título do artigo. Normalmente é mais curto do que o título de um artigo, para se ajustar melhor ao menu.
- Selecione um tipo de item de menu: em "Artigos" selecione "Artigo único".
- Selecione o artigo: selecione o artigo que acabámos de criar.
- Vá ao sítio e atualize a página. Parabéns: já pode clicar no item de menu para ver o seu artigo.
Introdução
Escreva a introdução: o que vai aprender neste tutorial e que pré-requisitos são necessários.
Filtrar informação adicional
Podemos deixar de fora algo do que foi escrito até agora? Bem, no passo 2 da criação de um item de menu mencionei que o título do item de menu não tem de ser igual ao título do artigo. Será essa uma adição necessária a este tutorial? Se não, então é melhor deixá-la de fora por agora. Mas dá uma pista para um artigo mais especializado sobre títulos de artigos e títulos de menus e quando são exibidos, envolvendo as opções gerais do artigo, as configurações individuais do artigo no separador de opções, as configurações do item de menu no separador de opções do item de menu e mais. Também seria bom fazer um artigo do tipo referência sobre como artigos, categorias e itens de menu funcionam em conjunto; nesse artigo procure ser completo, listando todas as possibilidades. Um guia prático especializado poderia ser: "Como exibir o título do artigo?", mostrando as configurações gerais do artigo, e nas configurações individuais do artigo e do item de menu. Um artigo do tipo explicação poderia falar sobre o motivo pelo qual o Joomla usa "artigo" onde, por exemplo, o WordPress usa "post", ou como o artigo é apresentado na página final.
Conclusão
Resuma tudo num sumário. E mencione alguns possíveis passos seguintes para aprender mais (como: um tutorial sobre como adicionar uma categoria ou um guia prático sobre o atalho guardar-para-menu).
Imagens e gráficos
Faça capturas de ecrã mostrando os botões e campos envolvidos na criação de um artigo e de um item de menu. Marque os botões e campos envolvidos.
Para clareza, pode adicionar um diagrama mostrando como um artigo é colocado "sob" um item de menu.
Adicionar referências, guias práticos e explicações
Coloque toda a informação e instruções adicionais em artigos separados.
Visão geral
Se tiver múltiplos artigos sobre um tópico, deve fazer um artigo de visão geral, explicando como os artigos se relacionam e por onde começar.
Exercício
Comece a fazer o tutorial acima sobre como criar e publicar um artigo no Joomla. A melhor forma de aprender é fazendo. Vamos publicar um exemplo de como isto pode ficar no manual de utilizador atual neste sítio. mas teríamos todo o gosto em colocar aqui a sua versão se conseguir melhorar a atual.
(este artigo foi também publicado na Joomla Community Magazine de fevereiro de 2025)