As equipas de produtos e as equipas de software partilham um mesmo "bugbear": documentação.
A documentação do produto refere-se a manuais e guias orientados para o utilizador que explicam o fluxo de trabalho e a interface do utilizador de um produto. Como pode o utilizador médio ser produtivo com este produto? Neste sentido, a documentação do produto pode ser utilizada para produtos de software.
A documentação de software refere-se às tecnologias subjacentes, pré-requisitos, e atributos configuráveis de um produto de software. Como é que os administradores de TI configuram, monitorizam, hospedam, e implementam o produto de software para os utilizadores? Este tipo de documentação é importante, especialmente quando múltiplas versões ou filiais são adicionadas à mistura.
De certa forma, a documentação do produto é como ensinar alguém a conduzir um carro. A roda gira o carro, o pedal do acelerador move o carro, o pedal do travão pára o carro. A documentação de software ensina alguém como funciona o carro. A roda é ligada ao eixo dianteiro que gira os pneus dianteiros para alterar o curso da viagem; o acelerador aumenta o fluxo de ar para o motor, o que consome mais combustível, gerando torque e potência.
Ambos os tipos de documentação são importantes. Educa-se os utilizadores, e educam-se os administradores e programadores. É óptimo mostrar às pessoas como conduzir um carro, mas se ninguém sabe como o carro funciona, o que acontece quando o carro avaria?
Pequenas diferenças entre documentação de produto e de software
Há pequenas diferenças a ter em conta com a documentação do produto e do software:
Software e Documentação de Produto: Público-alvo e Persona
A documentação do produto destina-se a um único público; o utilizador. Assume que o utilizador não tem conhecimentos técnicos, comunicando em inglês simples com um jargão mínimo. Muito semelhante a um estágio técnico versus um diploma universitário, educa as pessoas sobre como fazer as coisas, com menos ênfase no conhecimento teórico ou conceptual.
A documentação de software é dirigida a administradores de TI, engenheiros e programadores. Abrange a concepção e arquitectura de software, instruções de configuração de linha de comando, API e suporte de integração, gestão de dados e relatórios, topologia de rede - basicamente as engrenagens que fazem a máquina funcionar. Estes documentos formam uma fonte de verdade única (SSOT) a que o pessoal de TI pode fazer referência ao monitorizar e solucionar problemas da aplicação de software.
Software e Documentação de Produto: Frequências de actualização
A documentação do software deve ser constantemente actualizada à medida que novos compromissos são fundidos no canal de lançamento principal. A documentação do software deve destacar novas funções e comandos, e depreciar características antigas. As dependências novas ou em mudança devem ser documentadas, e o suporte de funcionalidades em todas as plataformas alvo deve ser clarificado - tal como uma funcionalidade que funcione no Windows, mas não no Linux.
A documentação do produto só precisa de ser actualizada quando as edições de software subjacentes provocam uma mudança no fluxo de trabalho ou na usabilidade. Um programador altera o código para um gateway de pagamento, mas o processo de pagamento para os utilizadores permanece o mesmo, pelo que não são necessárias actualizações.
Isto mostra uma hierarquia natural para a documentação de produtos de software. A documentação técnica do software constitui a base, e a subsequente documentação do produto é baseada nesta base. Por conseguinte, o foco deve ser o de fazer uma grande documentação de software, uma vez que gera uma documentação de produto ainda maior.
Exemplo de estruturas de formatação para documentação de produtos e software
Uma peça de documentação do produto poderia seguir este enquadramento:
Nome do produto
Visão geral do produto Finalidade
Guia de configuração
Função 1 Explicação e Imagens
Função 2 Explicação e Imagens
Ligações de apoio ao cliente
Da mesma forma, uma peça de documentação de software poderia seguir este quadro:
Nome do software
Visão geral do software Finalidade
Dependências do software
Guia de instalação
Função 1 Explicação e Imagens
Função 2 Explicação e Imagens
Ligações de apoio técnico
Claramente, estes dois tipos de documentação estão intimamente relacionados entre si e seguem uma estrutura semelhante. Isto significa que as equipas de produtos e software têm muito a aprender uma com a outra, e muito potencial quando se trabalha em colaboração na documentação.
Equipas de Documentação de Produtos e Software Podem Complementar-se
Existem semelhanças acentuadas entre a documentação do produto e o software. Isto apresenta a questão: as equipas de produto e de software podem trabalhar em conjunto?
Sim, eles podem, e devem!
As equipas de software compreendem o jargão técnico e as tecnologias subjacentes. As equipas de produtos compreendem o que os utilizadores vêem, querem e precisam; a experiência do utilizador. Os redactores de documentação de software podem fornecer informação técnica detalhada, e os redactores de documentação de produto podem diluir os detalhes técnicos para consumo por um público leigo.
Imagine tentar explicar algo em termos leigos, sem ter a compreensão de alto nível necessária para formular algo que um leigo entenderia. É o que acontece quando a documentação do produto é criada antes da documentação do software.
O que é a mecânica quântica? O gato de Schrodinger é provavelmente o primeiro pensamento na sua cabeça! Mas o que é que a mecânica quântica tem a ver com os gatos? Para o utilizador, não é importante. Para um físico, significa tudo.
Comece Com Documentação de Software, Termine Com Melhor Documentação de Produto em Docsie
Para concluir, há muitos benefícios quando se utiliza a documentação de software como modelo para posterior documentação do produto. A documentação de software deve funcionar como uma fonte única de verdade para o pessoal de TI e para os redactores de documentação de produtos. Depois de escrita, os redactores de documentação de produto terão a clareza e a compreensão necessárias para simplificar e partilhar conhecimentos de fácil utilização com os clientes, com orientação técnica para a revisão e garantia de qualidade.
Simplesmente, ao começar com uma grande documentação de software, os seus escritores podem elaborar ainda melhor documentação de produtos!
Comece a elaborar documentação que ajude os seus clientes a fazer mais. Inscreva-se no nosso plano de arranque (forever free!) e entregue documentação que deleite com Docsie!