Tanto as equipes de produtos quanto as equipes de software têm um problema em comum: a documentação.
A documentação do produto refere-se a manuais e guias voltados para o usuário que explicam o fluxo de trabalho e a interface do usuário de um produto. Como o usuário comum pode ser produtivo com esse produto? Nesse sentido, a documentação do produto pode ser usada para produtos de software.
A documentação de software refere-se às tecnologias subjacentes, aos pré-requisitos e aos atributos configuráveis de um produto de software. Como os administradores de TI configuram, monitoram, hospedam e implementam o produto de software para os usuários? Esse tipo de documentação é importante, especialmente quando várias versões ou ramificações são adicionadas à mistura.
De certa forma, a documentação do produto é como ensinar alguém a dirigir um carro. O volante gira o carro, o pedal do acelerador move o carro, o pedal do freio para o carro. A documentação do software ensina a alguém como o carro funciona. A roda está conectada ao eixo dianteiro, que gira os pneus dianteiros para alterar o curso da viagem; o acelerador aumenta o fluxo de ar para o motor, que consome mais combustível, gerando torque e potência.
Os dois tipos de documentação são importantes. Um educa os usuários e o outro educa os administradores e desenvolvedores. É ótimo mostrar às pessoas como dirigir um carro, mas se ninguém souber como o carro funciona, o que acontecerá quando ele quebrar?
Pequenas diferenças entre documentação de produtos e de software
Há pequenas diferenças que devem ser observadas na documentação de produtos e de software:
Documentação de software e de produto: Público-alvo e persona
A documentação do produto atende a um único público: o usuário. Ela pressupõe que o usuário não tenha conhecimento técnico, comunicando-se em inglês simples com o mínimo de jargão. Muito parecido com um aprendizado técnico versus um diploma universitário, ele educa as pessoas sobre como fazer as coisas, com menos foco no conhecimento teórico ou conceitual.
A documentação de software é voltada para administradores de TI, engenheiros e desenvolvedores. Ela abrange o design e a arquitetura do software, as instruções de configuração da linha de comando, o suporte à API e à integração, o gerenciamento de dados e os relatórios, a topologia da rede - basicamente, as engrenagens que fazem a máquina funcionar. Esses documentos formam uma fonte única de verdade (SSOT) que a equipe de TI pode consultar ao monitorar e solucionar problemas do aplicativo de software.
Documentação do software e do produto: Frequências de atualização
A documentação do software deve ser atualizada de forma consistente à medida que novos commits são mesclados no canal de versão principal. A documentação do software deve destacar as novas funções e comandos e descontinuar os recursos antigos. As dependências novas ou alteradas devem ser documentadas e o suporte a recursos em todas as plataformas de destino deve ser esclarecido, como o fato de um recurso funcionar no Windows, mas não no Linux.
A documentação do produto só precisa ser atualizada quando as edições do software subjacente provocam uma mudança no fluxo de trabalho ou na usabilidade. Um desenvolvedor altera o código de um gateway de pagamento, mas o processo de pagamento para os usuários permanece o mesmo, portanto, não são necessárias atualizações.
Isso mostra uma hierarquia natural para a documentação de produtos de software. A documentação técnica do software forma a base, e a documentação subsequente do produto é baseada nessa base. Portanto, o foco deve estar em criar uma excelente documentação de software, pois ela gera uma documentação de produto ainda melhor.
Exemplo de estruturas de formatação para documentação de produtos e software
Uma parte da documentação de um produto poderia seguir esta estrutura:
-
Nome do produto
-
Visão geral do objetivo do produto
-
Guia de configuração
-
Explicação e imagens do recurso 1
-
Explicação e imagens do recurso 2
-
Links de suporte ao cliente
Da mesma forma, uma parte da documentação do software poderia seguir essa estrutura:
-
Nome do software
-
Visão geral da finalidade do software
-
Dependências de software
-
Guia de instalação
-
Explicação e imagens da função 1
-
Explicação e imagens da função 2
-
Links de suporte técnico
Claramente, esses dois tipos de documentação estão intimamente relacionados entre si e seguem uma estrutura semelhante. Isso significa que as equipes de produtos e de software têm muito a aprender umas com as outras e muito potencial ao trabalharem de forma colaborativa na documentação.
As equipes de documentação de produtos e de software podem se complementar
Há grandes semelhanças entre a documentação de produtos e a de software. Isso levanta a questão: as equipes de produto e de software podem trabalhar juntas?
Sim, elas podem e devem!
As equipes de software entendem o jargão técnico e as tecnologias subjacentes. As equipes de produtos entendem o que os usuários veem, querem e precisam; a experiência do usuário. Os redatores de documentação de software podem fornecer informações técnicas detalhadas, e os redatores de documentação de produtos podem diluir os detalhes técnicos para serem consumidos por um público leigo.
Imagine tentar explicar algo em termos leigos, sem ter o conhecimento de alto nível necessário para formular algo que um leigo entenderia. Isso é o que acontece quando a documentação do produto é criada antes da documentação do software.
O que é mecânica quântica? O gato de Schrodinger é provavelmente o primeiro pensamento que vem à sua cabeça! Mas o que a mecânica quântica tem a ver com gatos? Para o usuário, isso não é importante. Para um físico, ela significa tudo.
Comece com a documentação do software e termine com uma melhor documentação do produto no Docsie
Para concluir, há muitos benefícios em usar a documentação do software como modelo para a documentação subsequente do produto. A documentação do software deve funcionar como uma fonte única de verdade para a equipe de TI e para os redatores da documentação do produto. Depois de redigida, os redatores da documentação do produto terão clareza e compreensão para simplificar e compartilhar conhecimento de fácil utilização 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, seus redatores podem criar uma documentação de produto ainda melhor!
Comece a criar uma documentação que ajude seus clientes a fazer mais. Inscreva-se em nosso plano de inicialização (forever free!) e ofereça uma documentação deliciosa com a Docsie!