User Documentation Neste tutorial você pode aprender como fazer um tutorial.
Um tutorial é uma lição que o guia por uma série de passos práticos. Ele oferece uma experiência de aprendizado ao fazer algo. É a melhor forma de conhecer um assunto com o qual você ainda não está familiarizado. Tutoriais são cruciais em qualquer documentação: eles apresentam o ambiente aos recém-chegados, guiam os primeiros passos, são a vitrine, e proporcionam uma experiência agradável e fácil de um tópico. Um dos "truques" para conseguir isso é deixar de fora tudo que possa distrair no processo de aprendizado. Por exemplo:
- Formas alternativas de fazer algo ou formas muito específicas de fazer algo.
- Referências completas de todas as opções e uma descrição técnica de sua estrutura.
- Explicações detalhadas e contextos históricos.
Essas informações extras são melhor fornecidas separadamente. Evite ao máximo misturá-las, pois isso só vai confundir o tutorial. Este é o princípio principal do Framework Diátaxis, uma forma sistemática de melhorar a documentação. Coloque as informações extras mencionadas acima em guias de como fazer, referências e explicações respectivas. Nos guias de como fazer você pode encontrar rapidamente como realizar algo específico. Nas referências você pode consultar como as coisas funcionam, quais opções elas têm e onde encontrar mais informações. Com as explicações você pode aprofundar sua compreensão do tópico.
Embora um tutorial ofereça uma introdução a um tópico, ele não é exclusivamente voltado para iniciantes. Também pode ser uma introdução a um tópico avançado! Seja claro no início do seu tutorial sobre qual conhecimento ou habilidade é necessário para conseguir realizar o tutorial.
Se você ensina alguém a cozinhar, precisa explicar coisas como técnicas de corte, como usar um forno e outras noções básicas de cozinha. Você começa com uma receita simples, de preferência algo que facilmente produza um bom resultado final. Esse resultado final em si não é o objetivo principal: você quer ensinar algumas habilidades. É isso que um tutorial faz. Alguém que já sabe cozinhar e quer fazer algo específico não precisa de um tutorial assim, mas sim de uma receita. As receitas são os guias de como fazer 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 você achou confusas ou que levaram algum tempo para entender. Há alguma pergunta sobre o assunto no fórum?
- Quais 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 é.
- Há algum conhecimento ou habilidade específica necessária para ensinar em seu tutorial?
- Crie um exemplo no qual você possa usar todos os conceitos e habilidades que deseja transmitir no tutorial. Torne o exemplo o mais simples possível.
- Defina e escreva etapas para chegar a um resultado final. Cada etapa 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 você aprenderá neste tutorial? Mencione quaisquer pré-requisitos necessários para fazer o tutorial.
- Escreva o resumo. O que aprendemos? Você também pode mencionar quais os próximos passos a serem tomados para aprender mais.
- Adicione capturas de tela com anotações para ilustrar as ações a serem tomadas. Dica: use números na captura de tela e forneça explicações no texto. Isso facilita a reutilização da sua captura de tela em traduções e minimiza o esforço para produzir capturas de tela específicas do idioma.
- Adicione diagramas para explicar estruturas, relações e processos.
- Adicione os artigos que acompanham com explicações, referências e guias de como fazer.
- Coloque todos os artigos de um assunto sob um artigo de visão geral, explicando o que é cada coisa, como eles se relacionam e por onde começar.
Exemplo: Criar e publicar um artigo no Joomla
Como exemplo, vamos criar um tutorial de como criar e publicar um artigo sob um item de menu no Joomla.
Coleta de informações
Em nosso manual do usuário você encontrará artigos relevantes em "Primeiros passos", "Artigos" e "Menus". Muitas vezes é confuso, ao começar com o Joomla, que você não veja um artigo depois de tê-lo criado, mesmo que o tenha marcado como "publicado". Para ver o artigo, é necessário haver um link para ele. Existem várias maneiras de criar esse link (como um item de menu ou uma disposição (layout) de blog de categoria, ou colocando-o na disposição (layout) de blog da página inicial marcando o artigo como destacado, ou vinculando-o a partir de outro artigo), mas agora vamos nos concentrar em disponibilizar o artigo por meio de um item de menu.
Conceitos & Habilidades
Temos 'conteúdo', 'artigo', 'menu' e 'item de menu'. Precisamos esclarecer esses termos. Mostramos onde encontrar essas coisas no menu administrativo. Deixamos de lado 'categorias' ou 'destacado' neste tutorial.
Pré-requisitos
Você precisa ter acesso ao lado administrativo de um site Joomla em funcionamento e saber como fazer login.
Objetivo
Nosso objetivo é aprender a criar um novo artigo no Joomla e um novo item de menu sob o qual colocamos nosso artigo.
Passos
Siga os passos abaixo para atingir nosso objetivo:
A. Criar um artigo
- Faça login no seu painel administrativo do Joomla.
- Primeiro vamos criar o artigo. Navegue até o menu "Conteúdo" à esquerda e selecione "Artigos".
- Clique em "Novo" para criar um novo artigo.
- Digite um título e conteúdo para o seu artigo.
- Clique em "Salvar e fechar" para salvar seu artigo.
B. Criar um item de menu vinculado ao artigo
para exibir o artigo no site, vamos criar um item de menu vinculado ao artigo. Navegue até o menu "Menus" à esquerda e selecione "Menu Principal".
- Assim como com um artigo, clique em "Novo" para criar um novo item de menu.
- Digite um título para o seu item de menu. Este é o título como ele aparecerá no menu. Não precisa ser o mesmo título do artigo. Normalmente é mais curto que o título de um artigo para caber melhor no menu.
- Selecionar um tipo de item de menu: em "Artigos" selecione "Artigo único".
- Selecionar o artigo: selecione o artigo que acabamos de criar.
- Vá até o site e atualize a página. Parabéns: agora você pode clicar no item de menu para ver seu artigo.
Introdução
Escreva a introdução: o que você vai aprender neste tutorial e quais pré-requisitos são necessários.
Filtrar informações adicionais
Podemos deixar de lado 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 precisa ser o mesmo que o título do artigo. Essa é uma adição necessária a este tutorial? Se não for, é melhor deixarmos isso de lado por enquanto. Mas isso dá uma pista para um artigo mais especializado sobre títulos de artigos e títulos de menus e quando eles são exibidos, envolvendo as opções gerais do artigo, as configurações individuais do artigo na aba de opções, as configurações do item de menu na aba de opções do item de menu e mais. Também seria bom criar um artigo do tipo referência sobre como artigos, categorias e itens de menu funcionam juntos; nesse artigo, tente ser completo, listando todas as possibilidades. Um artigo especializado de guia de como fazer poderia ser: "Como exibir o título do artigo?", mostrando as configurações nas configurações gerais do artigo, e nas configurações individuais do artigo e do item de menu. Um artigo do tipo explicações poderia contar algo sobre o contexto de por que o Joomla usa "artigo" onde, por exemplo, o WordPress usa "post", ou como o artigo é renderizado na página final.
Conclusão
Resuma tudo em um sumário. E mencione alguns possíveis próximos passos para aprender mais (como: um tutorial sobre como adicionar uma categoria ou um guia de como fazer sobre o atalho salvar-para-menu).
Imagens e gráficos
Faça capturas de tela mostrando os botões e campos envolvidos na criação de um artigo e um item de menu. Marque os botões e campos envolvidos.
Para maior clareza, você pode adicionar um diagrama mostrando como um artigo é colocado "sob" um item de menu.
Adicionar referências, guias de como fazer e explicações
Coloque todas as informações e instruções adicionais em artigos separados.
Visão geral
Se você tiver vários artigos sobre um mesmo tópico, deve criar 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. Publicaremos um exemplo de como isso pode ficar no manual do usuário atual deste site. Mas ficaremos felizes em colocar a sua versão aqui, se puder melhorar a atual.
(este artigo também foi publicado na Joomla Community Magazine de fevereiro de 2025)