As equipas de produto e as equipas de software partilham um problema comum: a documentação.
A documentação de produto refere-se aos manuais e guias destinados aos utilizadores que explicam o fluxo de trabalho e a interface de um produto. Como pode o utilizador comum ser produtivo com este produto? Neste sentido, a documentação de produto pode ser usada 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, alojam e implementam o produto de software para os utilizadores? Este tipo de documentação é importante, especialmente quando são adicionadas múltiplas versões ou ramos.
De certa forma, a documentação de produto é como ensinar alguém a conduzir um carro. O volante vira o carro, o acelerador move o carro, o travão para o carro. A documentação de software ensina como o carro funciona. O volante está ligado ao eixo dianteiro que faz girar os pneus frontais para alterar a direção; o acelerador aumenta o fluxo de ar para o motor que, por sua vez, consome mais combustível, gerando binário e potência.
Ambos os tipos de documentação são importantes. Um educa os utilizadores e o outro educa administradores e programadores. É ótimo mostrar às pessoas como conduzir um carro, mas se ninguém souber como o carro funciona, o que acontece quando o carro avaria?
Pequenas Diferenças Entre Documentação de Produto e de Software¶
Existem pequenas diferenças a ter em conta entre a documentação de produto e de software:
Documentação de Software e Produto: Público-Alvo e Persona¶
A documentação de produto destina-se a um único público: o utilizador. Assume que o utilizador não tem conhecimentos técnicos, comunicando em linguagem simples com mínimo de jargão. Tal como uma aprendizagem técnica em comparação com um curso universitário, educa as pessoas sobre como fazer as coisas, com menos foco no conhecimento teórico ou conceptual.
A documentação de software é direcionada para administradores de TI, engenheiros e programadores. Abrange o design e a arquitetura do software, instruções de configuração por linha de comandos, suporte a API e 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 única fonte de verdade (SSOT) a que o pessoal de TI pode recorrer ao monitorizar e resolver problemas da aplicação.
Documentação de Software e Produto: Frequência de Atualizações¶
A documentação de software deve ser atualizada consistentemente à medida que novos commits são incorporados no canal principal de lançamento. A documentação de software deve destacar novas funções e comandos, e descontinuar recursos antigos. Novas dependências ou alterações devem ser documentadas, e o suporte de funcionalidades em todas as plataformas-alvo deve ser esclarecido – como uma funcionalidade que funciona no Windows, mas não no Linux.
A documentação de produto só precisa de ser atualizada quando alterações no software subjacente provocam uma mudança no fluxo de trabalho ou na usabilidade. Um programador altera o código de um gateway de pagamento, mas o processo de pagamento para os utilizadores permanece o mesmo, pelo que não são necessárias atualizações.
Isto mostra uma hierarquia natural para a documentação de produtos de software. A documentação técnica de software forma a base, e a subsequente documentação de produto assenta nesta fundação. Portanto, o foco deve estar em criar uma excelente documentação de software, pois esta origina uma documentação de produto ainda melhor.
Exemplos de Estruturas para Documentação de Produto e Software¶
Uma documentação de produto poderia seguir esta estrutura:
-
Nome do Produto
-
Visão Geral do Propósito do Produto
-
Guia de Configuração
-
Explicação e Imagens da Funcionalidade 1
-
Explicação e Imagens da Funcionalidade 2
-
Ligações para Apoio ao Cliente
Da mesma forma, uma documentação de software poderia seguir esta estrutura:
-
Nome do Software
-
Visão Geral do Propósito do Software
-
Dependências do Software
-
Guia de Instalação
-
Explicação e Imagens da Função 1
-
Explicação e Imagens da Função 2
-
Ligações para Suporte Técnico
Claramente, estes dois tipos de documentação estão intimamente relacionados e seguem uma estrutura semelhante. Isto significa que as equipas de produto e de software têm muito a aprender umas com as outras, e muito potencial quando trabalham em colaboração na documentação.
As Equipas de Documentação de Produto e Software Podem Complementar-se¶
Existem semelhanças notáveis entre a documentação de produto e de software. Isto levanta a questão: podem as equipas de produto e de software trabalhar em conjunto?
Sim, podem e devem!
As equipas de software compreendem o jargão técnico e as tecnologias subjacentes. As equipas de produto compreendem o que os utilizadores veem, querem e precisam; a experiência do utilizador. Os redatores de documentação de software podem fornecer informações técnicas detalhadas, e os redatores de documentação de produto podem simplificar os detalhes técnicos para consumo por um público leigo.
Imagine tentar explicar algo em termos simples, sem ter o conhecimento de alto nível necessário para formular algo que um leigo entenderia. É isso que acontece quando a documentação de produto é criada antes da documentação de software.
O que é mecânica quântica? O gato de Schrodinger é provavelmente o primeiro pensamento que lhe vem à cabeça! Mas o que tem a mecânica quântica a ver com gatos? Para o utilizador, isso não é importante. Para um físico, significa tudo.
Comece com Documentação de Software, Termine com Melhor Documentação de Produto no Docsie¶
Concluindo, há muitos benefícios ao usar a documentação de software como modelo para a subsequente documentação de produto. A documentação de software deve atuar como uma única fonte de verdade para o pessoal de TI e redatores de documentação de produto. Depois de escrita, os redatores de documentação de produto terão a clareza e compreensão necessárias para simplificar e partilhar conhecimento acessível com os clientes, com orientação técnica para revisão e garantia de qualidade.
Simplesmente, ao começar com uma excelente documentação de software, os seus redatores podem criar uma documentação de produto ainda melhor!
Comece a criar documentação que ajuda os seus clientes a fazer mais. Registe-se no nosso plano Startup (gratuito para sempre!) e proporcione documentação de excelência com o Docsie!