Áina Rocha e Filipe Franco, Technical Writers, @SISCOG | 4 min leitura
___________
No meio da codificação em Lisp e Python, e de diferentes sistemas e produtos, a Equipa de Documentação do Utilizador é formada com uma missão:
criar um guia claro para apoiar os utilizadores finais no seu percurso pelos produtos de software da SISCOG.
ERA UMA VEZ
Tudo começou tal como a maioria das coisas: por necessidade.
Seja por esquecimento de como executar certos passos de uma operação de software ou por achar difícil compreender como os produtos funcionam, tornou-se claro que os produtos de software da SISCOG precisavam de um processo de documentação para apoiar os clientes no planeamento e gestão da utilização dos seus recursos.
No entanto, os manuais do utilizador nem sempre foram produzidos por uma equipa designada. No início, a maioria dos nossos manuais do utilizador eram produzidos por quem realizava os testes, enquanto trabalhava nos produtos, utilizando software de escrita convencional como ferramenta principal. Rapidamente se tornou evidente que, devido às múltiplas operações disponíveis nos produtos da SISCOG, e às diferentes customizações dos sistemas da SISCOG, o desenvolvimento de manuais do utilizador necessitaria de uma base muito mais estável.
Quando a nossa atual ferramenta de software de escrita entrou em cena, a equipa de testes já tinha composto muitos ficheiros que continham instruções sobre como utilizar os nossos produtos. No entanto, era claro que lidar com essa quantidade de dados era um trabalho a tempo inteiro. E foi assim que nasceu a Equipa de Documentação do Utilizador (EDU).
A missão da nossa Equipa de Documentação do Utilizador: criar um guia claro para apoiar os utilizadores finais no seu percurso pelos produtos de software da SISCOG.
______________________
A DOMINAR A DOCUMENTAÇÃO DO UTILIZADOR
Um dos principais desafios na escrita de documentação sobre os produtos da SISCOG continua a ser o dominar as diferenças entre sistemas - o produto que é adaptado à realidade de um cliente - e garantir que os manuais do utilizador sejam o mais precisos possível, bem como atualizados, de acordo com as versões mais recentes dos produtos, como o ONTIME, FLEET e CREWS.
A nossa ferramenta de software atual ajuda-nos a evitar escrever a mesma página para cada manual do utilizador do sistema. Em vez disso, podemos marcar qualquer parte de texto que contenha uma particularidade do sistema para que apenas apareça no manual do utilizador pretendido desse sistema. Desta forma, à medida que reunimos todos os detalhes e escrevemos instruções sobre as funcionalidades, operações ou conceitos do sistema na mesma página, podemos também gerar uma página completamente diferente para cada sistema.
Claro que manter os manuais do utilizador atualizados é um trabalho diário. À medida que acompanhamos as notas de lançamento (release notes) dos produtos e participamos em equipas Ágeis, escrever manuais sobre os produtos e sistemas da SISCOG que evoluem constantemente é uma tarefa desafiante que demonstra a importância do trabalho em equipa e da cooperação com outros departamentos.
Atualmente, com ficheiros que cobrem instruções sobre as principais operações e um software que nos fornece estrutura e ferramentas para trabalhar, podemos concentrar-nos em escrever melhorias e métodos que auxiliam a compreensão do utilizador quando confrontados com os conceitos e operações no software da SISCOG.
Uma boa prática para captar a atenção do utilizador, e desconstruir conceitos complexos em ideias mais pequenas e claras, é através da utilização de fluxogramas e diagramas, tal como fazemos para o conceito da “Árvore da Realidade” no exemplo abaixo.
Exemplo de um diagrama que ilustra o conceito de “Árvore da Realidade”.
Para além disso, outra abordagem para conceber os manuais do utilizador como uma leitura fluída é utilizar GIFs para exemplificar os passos que descrevemos e os resultados esperados de uma operação. Para evitar leituras exaustivas, usamos o método Every page is page one (EPPO) de modo a que cada artigo corresponda a uma pergunta diferente e seja independente uns dos outros.
Para facilitar a navegação, o utilizador pode abrir o manual do utilizador diretamente a partir do software da SISCOG ao pressionar o botão F1 sobre uma opção do menu. Esta ação irá abrir o manual do utilizador num artigo específico com instruções sobre “como fazer” (how-to) na opção de menu.
Acreditamos que os artigos de "como fazer" (how-to) são uma boa solução num dia em que a memória falha e não nos lembramos da sequência de passos para a operação. No entanto, estes artigos não fornecem detalhes e explicações que permitam compreender a lógica por trás do processo.
Para isso, diversificamos o tipo de documentação.
Empatia é o futuro
Num esforço para fornecer todo o apoio necessário aos utilizadores de software, escrever um manual do utilizador é como um exercício de empatia: Como utilizador final, quais seriam as minhas perguntas? Dificuldades? O que teria dificuldade em lembrar?
Ao nos colocarmos no lugar do utilizador final e recolhermos informação de questionários, percebemos que as suas necessidades vão além das instruções de “como fazer”. Precisamos de responder não apenas ao “como”, mas também ao “o quê” e ao “porquê”.
Seguindo esta perspetiva, pretendemos escrever documentação diversificada que inclua tutoriais, artigos explicativos e perguntas frequentes (FAQs).
Diferentes tipos de documentação têm objetivos manifestamente diferentes e, portanto, produzem diferentes tipos de apoio para o utilizador final. Enquanto exploramos os nossos produtos em busca de perguntas que o utilizador final possa ter, também nos esforçamos por encontrar a melhor forma de transmitir a mensagem de forma eficaz.
Escrever um manual do utilizador é como um exercício de empatia.
______________________
Assim como os nossos produtos estão constantemente a evoluir, também a nossa documentação deve evoluir.
Em vez de nos contentarmos com documentação padronizada, estamos sempre à procura de novas formas de melhorar e inovar a nossa abordagem para ajudar os nossos clientes e acompanhá-los nas diferentes etapas da sua jornada de aprendizagem.
E embora tenha sido um desafio, o conhecimento e a experiência que adquirimos tem-se revelado incrivelmente gratificante.