Que estilo de documentação devem utilizar os gestores de produto para comunicar a mensagem apropriada?

A documentação é uma das componentes mais cruciais e subvalorizadas de qualquer projecto de código aberto, e não deve ser encarada de ânimo leve.

Em geral, a maioria dos projectos de código aberto não recebem a atenção adequada simplesmente porque os seus autores não estão realmente interessados, são incapazes de, ou não têm tempo para criar um ambiente de documentação eficaz para o seu API e documentação de produtos.

Embora a sua candidatura possa ser excelente, se a documentação for inadequada, os consumidores não poderão beneficiar da sua utilização.

No entanto, mesmo que não tenham outra opção senão utilizá-lo por qualquer razão, não poderão fazê-lo com sucesso ou da maneira que você gostaria que o fizessem.

Compreender como produzir documentação excelente requer um volume de trabalho significativo, tal como a revisão periódica de outros projectos de documentação. Mas acredite na minha palavra - como alguém que criou uma pletora de documentação para a Docsie - se estiver a construir código que será utilizado por alguém que não você, e particularmente se essas pessoas forem seus clientes, o seu produto deve ser bem documentado, formatado e apresentado de forma dinâmica.

Quando se trata de tutoriais, como fazer, explicações, e referências, qual é a diferença?

Muitas pessoas acreditam erroneamente que as quatro frases se referem ao mesmo item. No entanto, elas expressam uma variedade de significados diversos. Estes diferentes tipos de documentações são bastante essenciais e têm algumas diferenças fundamentais:

Documentação tutória: Estes tipos de documentação são documentação baseada em informação orientada para a formação.

Como fazer Guias / Documentação de Guias do Utilizador: Os guias do utilizador expressam como resolver problemas específicos através de uma série de passos a fim de alcançar um objectivo específico.

Documentação explicativa: Trata-se de documentação do tipo artigo que foi concebida para ajudar o utilizador/leitor a obter uma compreensão mais profunda de um produto através de várias explicações e contexto de fundo.

Documentação de notas de referência: Esta documentação foi concebida para informar o utilizador da descrição de várias actualizações e utilizações de novas funcionalidades. Este tipo de documentação pode ser muito "em bruto" sob a forma de documentação de desenvolvimento, no entanto, podem também ser traduzidas em notas de lançamento mais fáceis de utilizar, que podem ser facilmente compreendidas pelo utilizador final.

Razões para produzir documentação de alta qualidade

Antes de prosseguir, é crucial compreender por que razão a redacção de documentação competente é uma necessidade muito importante mas pouco apreciada na sociedade de hoje. A disponibilidade de documentação extensa e bem escrita é um dos critérios mais importantes para conseguir uma adopção generalizada, particularmente em projectos de fonte aberta onde praticamente todas as acções estão disponíveis ao público e onde tais actividades desempenham um papel crucial para o sucesso do projecto.

Vejamos as razões mais importantes para escrever uma documentação eficaz.

Permite-lhe criar uma melhor experiência de bordo para os seus clientes.

Quando fornecer documentação adequada sobre o seu produto aos seus clientes, irá ajudá-los, fazendo-os sentir-se mais confortáveis com o seu produto, e protegidos pelas suas directrizes específicas. Deve fazer o seguinte para que isto ocorra:

1. Certifique-se de que a documentação do seu produto é visível e facilmente acessível, quer através de ligações em formato de papel, quer sob uma plataforma de documentação pesquisável.

2. Assegurar que estão bem escritas e ajudar o cliente a encontrar a sua resposta rápida e facilmente

Um conselho é escrever a sua documentação apenas uma vez, e será digerida uma e outra vez quando novos clientes forem trazidos a bordo pela sua empresa.

Como consequência, há menos inquéritos de apoio.

Os clientes que lêem e compreendem a sua documentação são mais propensos a comprar os seus bens. Quando os clientes não conseguem perceber nada, isso pode ser bastante agravante, e podem começar a culpar o seu produto.

Alguns clientes podem contactar instantaneamente ou enviar um e-mail ao pessoal de apoio se encontrarem um obstáculo; mas, se a documentação for atractiva, facilmente acessível e inteligível, poderão resolver os seus próprios problemas sem necessidade de o consultar, o que, por sua vez, os fará sentir mais capacitados.

Ajuda-o a apoiar a sua própria equipa.

Uma sólida base de conhecimentos também pode ser utilizada para ajudar os membros da sua própria equipa. Assim, a sua equipa interna deve ser informada sobre novas funcionalidades, roteiros planeados, documentação API, e tudo o mais que seja necessário para manter todos na mesma página.

Instruções passo a passo sobre como escrever documentação eficaz

Escrever a substância do documento e organizar esta actividade são duas tarefas inteiramente distintas de determinar o tom a utilizar e como assegurar que a sua documentação é compreensível. Como declarado por O'Reilly, existem 8 regras de excelente documentação:

1. Criar documentação que seja convidativa para o leitor.

2. Produzir documentação exaustiva que abranja todas as áreas do projecto.

3. Produzir material escumável que seja fácil de compreender.

4. Criar documentação que demonstre como utilizar o produto através de estudos de caso.

5. Escrever documentação que contenha repetição onde for necessário.

6. Escrever documentação que esteja em dia*

7. Criar documentação que seja simples de contribuir*.

8. Escrever documentação que seja simples de descobrir e compreender*.

Esses elementos estão principalmente relacionados com o conteúdo. Em seguida, vamos entrar no "como" de estruturar esta informação em seis passos:

Tomar uma decisão sobre o que deve gravar.

Leve algum tempo a considerar que tipo de documentação irá produzir antes de começar: é um tutorial, um documento de referência, um manual de instruções, ou uma explicação?

Tenha em atenção que a natureza do seu produto terá um impacto directo no tipo de documentação que será responsável pela sua criação.

Criar uma estrutura.

Construa primeiro uma base para a sua documentação. Isto pode ser algo muito pequeno no início, e pode compreender apenas alguns grupos, mas com o tempo, toda a plataforma sobre a qual está a construir começará a crescer em tamanho e complexidade. Deverá rever a sua estrutura organizacional regularmente.

Tenha em mente que é o instrutor, e que, em última análise, é responsável pela forma como os seus alunos aprendem na sua turma. Eles serão orientados pelas suas instruções; assim, quanto mais tempo gastar em estrutura, mais bem sucedidos serão os seus alunos nos seus esforços.

Tirar sempre partido de técnicas multimédia sonoras.

Certifique-se de que faz uso de vídeos, desenhos e estilos variados e ligue-os directamente à sua documentação. O Docsie permite incorporar qualquer um destes na nossa plataforma para facilitar este processo.

Não só ajudarão os consumidores a compreender melhor a informação que expressa, mas também darão uma fantástica Optimização para Motores de Pesquisa que levará a um maior número de leads de alta qualidade como resultado da sua documentação dinâmica.

Certificar-se de que é pesquisável.

Existem diferenças nas capacidades de pesquisa de diferentes plataformas de base de conhecimento - algumas delas apenas oferecem pesquisa básica sem capacidade de perfurar em segmentações (o que é tecnicamente bom se não tiver milhares de ficheiros), enquanto outras oferecem opções de pesquisa que lhe permitem pesquisar não só em documentos mas também em nomes de utilizador.

No entanto, há uma coisa que é crítica: deve estar a utilizar uma ferramenta que lhe permita pesquisar rapidamente. Uma funcionalidade de pesquisa incluída na aplicação torna simples a pesquisa de ficheiros e obter uma visualização prévia dos mesmos sem sair da aplicação.

Docsie permite-lhe ter uma navegação dinamicamente pesquisável para informação facilmente acessível.

Esforçar-se constantemente por melhorar e actualizar

A criação e utilização de documentos é difícil porque são rapidamente esquecidos pelos indivíduos que os geraram ou lucraram com eles. Os documentos também enfrentam uma série de desafios ao longo da sua viagem.

À medida que o tempo passa, a estrutura da pasta assume o aspecto de um cemitério, uma vez que a documentação mais antiga tende a permanecer numa posição inferior no ecrã do monitor.

Por isso, não se esqueça de voltar à sua antiga documentação e de fazer melhorias, bem como de encorajar os seus colegas a fazer o mesmo de vez em quando. Docsie permite-lhe criar actualizações através do nosso sistema de versões avançadas, que é simples e fácil de fazer.

Pensamentos finais:

Quer saber mais sobre como escrever documentação eficaz? Para profissionais de documentação de software, há uma tonelada de blogs e informação a ser encontrada aqui.