Confuso acerca da documentação do produto e do software? Não se preocupe, Eles são Um na Mesma!

Avatar of Author
Ciaran Sweet
on July 02, 2021 · · filed under Product Documentation Product Management Documentation Portals Product Updates Best Practices Technical Writing API Documentation Product Documentation Tutorials

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!


Subscribe to the newsletter

Stay up to date with our latest news and products