\u201cDocs or it didn’t happen\u201d (Documente ou n\u00e3o aconteceu) \u00e9 um mantra para qualquer pessoa que esteja criando um produto de software e significa que a documenta\u00e7\u00e3o \u00e9 mais do que um subproduto ou uma reflex\u00e3o tardia de seu projeto. Ela fecha a lacuna entre o desenvolvimento e os usu\u00e1rios de software, bem como as lacunas entre os envolvidos na cria\u00e7\u00e3o do software.<\/p>\r\n
O que \u00e9 documenta\u00e7\u00e3o t\u00e9cnica?<\/strong><\/h2>\r\nA documenta\u00e7\u00e3o t\u00e9cnica descreve e explica tudo o que est\u00e1 relacionado ao seu produto de software, desde a documenta\u00e7\u00e3o interna para equipes at\u00e9 a documenta\u00e7\u00e3o externa escrita para usu\u00e1rios finais.<\/strong> Ele abrange todos os documentos escritos relacionados ao desenvolvimento de produtos de software e muitos tipos diferentes s\u00e3o criados durante o ciclo de vida do desenvolvimento de software (SDLC).<\/p>\r\nEle descreve os recursos e a funcionalidade do produto de forma clara para que qualquer pessoa possa us\u00e1-lo. O objetivo principal \u00e9 explicar um aspecto espec\u00edfico do produto para o p\u00fablico-alvo. Embora seja apresentada de v\u00e1rias formas diferentes, a maior parte da documenta\u00e7\u00e3o t\u00e9cnica \u00e9 publicada on-line e normalmente \u00e9 escrita por redatores t\u00e9cnicos, desenvolvedores e gerentes de projeto.<\/p>\r\n
A documenta\u00e7\u00e3o t\u00e9cnica deve ser clara, concisa, precisa e na verdade resolver um problema para seus usu\u00e1rios.<\/p>\r\n
Import\u00e2ncia da documenta\u00e7\u00e3o t\u00e9cnica<\/strong><\/h2>\r\nA documenta\u00e7\u00e3o t\u00e9cnica \u00e9 de vital import\u00e2ncia para a sua empresa de software. Aqui est\u00e3o algumas raz\u00f5es.<\/p>\r\n
Permite a tomada de decis\u00e3o r\u00e1pida pela equipe do produto<\/strong><\/h3>\r\nQuando sua equipe de produtos tem acesso \u00e0 documenta\u00e7\u00e3o t\u00e9cnica correta, eles podem tomar decis\u00f5es muito mais r\u00e1pidas. Eles n\u00e3o t\u00eam que voltar a navegar por e-mails ou t\u00f3picos nas ferramentas de colabora\u00e7\u00e3o \u2014 podem em vez disso consultar instantaneamente os documentos produzidos ao lado do software que explica como tudo funciona e registra o racioc\u00ednio por tr\u00e1s das decis\u00f5es.<\/p>\r\n
Ajuda contextual para usu\u00e1rios<\/strong><\/h3>\r\nQuando os clientes estiverem usando o software, eles poder\u00e3o acessar a documenta\u00e7\u00e3o t\u00e9cnica junto com o produto para obter ajuda no uso da ferramenta. A documenta\u00e7\u00e3o pode ser exibida no aplicativo para que os clientes n\u00e3o precisem mudar de contexto quando tiverem problemas. Isso melhora a usabilidade e a experi\u00eancia gerais do seu produto de software.<\/p>\r\n
Ter uma documenta\u00e7\u00e3o t\u00e9cnica robusta facilita a divulga\u00e7\u00e3o de seu produto para clientes em potencial. Muitos clientes poder\u00e3o pesquisar detalhadamente como o seu produto funciona, e a documenta\u00e7\u00e3o t\u00e9cnica poder\u00e1 explicar os recursos do seu software com mais profundidade do que os materiais de marketing comuns.<\/p>\r\n
Reduz chamadas de suporte t\u00e9cnico<\/strong><\/h3>\r\nQuando voc\u00ea tem uma documenta\u00e7\u00e3o t\u00e9cnica abrangente, os clientes podem consultar os documentos quando tiverem problemas t\u00e9cnicos. Isso reduz o n\u00famero de chamadas recebidas na sua fila de suporte t\u00e9cnico e significa que voc\u00ea pode dar suporte a mais clientes com um or\u00e7amento menor. A maioria dos clientes prefere solucionar os problemas por conta pr\u00f3pria em vez de ficar esperando que uma pessoa os ajude.<\/p>\r\n
Registra ideias de desenvolvedores<\/strong><\/h3>\r\nA documenta\u00e7\u00e3o do seu software pode registrar as ideias que os desenvolvedores t\u00eam em rela\u00e7\u00e3o ao seu produto de software. Mesmo que voc\u00ea n\u00e3o as implemente imediatamente, mais adiante voc\u00ea poder\u00e1 procurar recursos que talvez queira considerar ou outras altera\u00e7\u00f5es que queira fazer. Os desenvolvedores n\u00e3o necessariamente se lembram de suas ideias mais tarde, portanto, sua documenta\u00e7\u00e3o \u00e9 um bom lugar para manter um registro.<\/p>\r\n
Fornece um roteiro para projetos futuros<\/strong><\/h3>\r\nSua documenta\u00e7\u00e3o t\u00e9cnica \u00e9 um roteiro para os projetos que voc\u00ea deseja desenvolver no futuro, registrando os planos que voc\u00ea tem para o desenvolvimento do seu produto e os novos recursos que est\u00e3o sendo preparados. Ela garante que todos na sua equipe estejam na mesma p\u00e1gina e trabalhando para atingir um \u00fanico objetivo.<\/p>\r\n
Melhora a comunica\u00e7\u00e3o com interessados e desenvolvedores<\/strong><\/h3>\r\nA documenta\u00e7\u00e3o \u00e9 uma forma importante de comunica\u00e7\u00e3o – as partes interessadas e os desenvolvedores n\u00e3o precisam conversar diretamente entre si para acessar informa\u00e7\u00f5es sobre o software. A documenta\u00e7\u00e3o salva o conhecimento para a posteridade e permite que a equipe analise o trabalho que foi conclu\u00eddo anteriormente para informar as decis\u00f5es futuras.<\/p>\r\n
Tipos de documenta\u00e7\u00e3o t\u00e9cnica com exemplos<\/strong><\/h2>\r\nExistem muitos tipos diferentes de documenta\u00e7\u00e3o t\u00e9cnica \u2013 passaremos por eles agora.<\/p>\r\n
Documenta\u00e7\u00e3o t\u00e9cnica no SDLC<\/strong><\/h3>\r\nEsta \u00e9 a documenta\u00e7\u00e3o de software nos bastidores destinada aos seus desenvolvedores e outros membros da equipe.<\/p>\r\n
Documenta\u00e7\u00e3o do administrador do sistema<\/strong> – melhora \u00e9 v\u00e1lida a seguran\u00e7a, documentando os detalhes e procedimentos da configura\u00e7\u00e3o que sustentam uma pol\u00edtica de seguran\u00e7a. Eles cobrem instala\u00e7\u00f5es e atualiza\u00e7\u00f5es que auxiliam um administrador do sistema com a manuten\u00e7\u00e3o de produtos.<\/p>\r\n![\"documenta\u00e7\u00e3o](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/01\/redhat_system_administartion_documentation.png\")
<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o de exig\u00eancia de produto<\/strong> \u2013 fornece um \u00fanico ponto de refer\u00eancia para os requisitos de entrada de design t\u00e9cnico de um produto e explica como o produto deve funcionar para atender \u00e0s necessidades dos clientes.<\/p>\r\n![\"documenta\u00e7\u00e3o](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/01\/product_requirement_documentation.png\")
<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o de design de experi\u00eancia do usu\u00e1rio<\/strong> – um documento de trabalho de um produto desde sua concep\u00e7\u00e3o at\u00e9 a vers\u00e3o atual, e eles incluem modelos de conte\u00fado, mapas de empatia, mapas de experi\u00eancia, modelos mentais e pessoas.<\/p>\r\n![\"experi\u00eancia](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/01\/user_experience_documentation.png\")
<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do c\u00f3digo-fonte<\/strong> \u2013 documenta\u00e7\u00e3o do software que garante que seu c\u00f3digo seja leg\u00edvel, possa ser compreendido rapidamente e seja f\u00e1cil de manter pelos desenvolvedores. Inclui coment\u00e1rios de c\u00f3digo que podem explicar partes de c\u00f3digo que n\u00e3o s\u00e3o \u00f3bvias.<\/p>\r\n![\"documenta\u00e7\u00e3o](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/01\/source_code_documentation.png\")
<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o da API<\/strong> <\/a>\u2013 permite que desenvolvedores trabalhem com a sua API e mostra se o seu software vai ou n\u00e3o resolver o problema deles.<\/p>\r\n![\"documenta\u00e7\u00e3o](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/01\/api_documentation.png\")
<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do guia de manuten\u00e7\u00e3o<\/strong> \u2013 diga ao usu\u00e1rio como manter o sistema de forma eficaz e pode incluir uma defini\u00e7\u00e3o do ambiente de suporte ao software. fun\u00e7\u00f5es e responsabilidades do pessoal de manuten\u00e7\u00e3o.<\/p>\r\n![\"Documenta\u00e7\u00e3o](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/01\/Maintenance_guide_documentation.png\")
<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do produto<\/h3>\r\n
Base de conhecimento de produtos<\/strong> \u2013 uma biblioteca de informa\u00e7\u00f5es sobre o produto do seu software que cont\u00e9m respostas para clientes procurando resolver problemas sozinhos.<\/p>\r\n![\"base](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/01\/product_knowledge_base.png\")
<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nManual do usu\u00e1rio<\/strong><\/a> – cont\u00e9m extensas informa\u00e7\u00f5es sobre como instalar e operar o produto, listando requisitos de hardware e software, explica\u00e7\u00e3o completa dos recursos do produto e como us\u00e1-los em toda a sua extens\u00e3o.<\/p>\r\n![\"manual](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/01\/user_manual.png\")
<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do projeto<\/a> – registra os principais detalhes do projeto e produz os documentos necess\u00e1rios para implementar um projeto com sucesso. Ele pode incluir propostas de projeto<\/a>, documentos de requisitos de neg\u00f3cios<\/a>, casos de neg\u00f3cios, planos de projeto e relat\u00f3rios de status do projeto.<\/p>\r\n![\"projeto](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/01\/project_plan_documentation.png\")
<\/p>\r\n
Fonte da imagem<\/p>\r\n
8 etapas para criar uma incr\u00edvel documenta\u00e7\u00e3o t\u00e9cnica<\/h2>\r\n
Aqui est\u00e3o as etapas que voc\u00ea precisa percorrer para criar uma documenta\u00e7\u00e3o t\u00e9cnica que seja bem sucedida e \u00fatil para seus usu\u00e1rios.<\/p>\r\n
Decida o tipo de p\u00fablico e o tipo de documenta\u00e7\u00e3o<\/h3>\r\n
Antes de mais nada, voc\u00ea precisa conhecer o p\u00fablico-alvo da sua documenta\u00e7\u00e3o. S\u00e3o os seus clientes, outros desenvolvedores, a equipe de produtos ou qualquer outra parte interessada? Ao saber quem \u00e9 o seu p\u00fablico, voc\u00ea poder\u00e1 adaptar o tom e o estilo da sua documenta\u00e7\u00e3o para torn\u00e1-la mais relevante e envolvente.
\r\nSe voc\u00ea n\u00e3o souber quem \u00e9 o seu p\u00fablico, sua documenta\u00e7\u00e3o n\u00e3o ter\u00e1 foco e n\u00e3o ser\u00e1 \u00fatil. Definir o p\u00fablico-alvo no est\u00e1gio inicial do processo de documenta\u00e7\u00e3o ajudar\u00e1 na cria\u00e7\u00e3o do documento e garantir\u00e1 que voc\u00ea tenha um alvo claramente definido.<\/p>\r\n
Pesquisa de t\u00f3picos<\/strong><\/h3>\r\nDepois de definir o p\u00fablico-alvo, voc\u00ea precisa pesquisar os t\u00f3picos que abordar\u00e1 em sua documenta\u00e7\u00e3o. Voc\u00ea n\u00e3o pode esperar escrever um conte\u00fado t\u00e9cnico eficaz se n\u00e3o tiver uma ideia clara dos t\u00f3picos sobre os quais escrever\u00e1. Nesse est\u00e1gio, \u00e9 uma boa ideia trabalhar com a sua equipe para fazer um brainstorming de diferentes t\u00f3picos e atribuir v\u00e1rias tarefas de pesquisa a diferentes membros da equipe.<\/p>\r\n
\u00c9 importante fazer perguntas a si mesmo:<\/p>\r\n
\r\n\t- Quais \u00e1reas queremos que nossa documenta\u00e7\u00e3o t\u00e9cnica inclua?<\/li>\r\n\t
- Qual \u00e9 o objetivo que queremos alcan\u00e7ar com nossa documenta\u00e7\u00e3o t\u00e9cnica?<\/li>\r\n\t
- J\u00e1 temos alguma documenta\u00e7\u00e3o existente com a qual podemos trabalhar?<\/li>\r\n<\/ul>\r\n
Certifique-se de que se trata de um esfor\u00e7o em equipe para pesquisar os t\u00f3picos \u2013 voc\u00ea n\u00e3o precisa ir sozinho.<\/p>\r\n
Capturar conhecimento<\/strong><\/h3>\r\nAo escrever sua documenta\u00e7\u00e3o, \u00e9 prov\u00e1vel que voc\u00ea n\u00e3o seja o \u00fanico autor. Ser\u00e1 necess\u00e1rio colaborar com outras partes interessadas da sua equipe para produzir a documenta\u00e7\u00e3o t\u00e9cnica. Nesse est\u00e1gio, voc\u00ea precisa trabalhar com especialistas no assunto para obter o conhecimento que ser\u00e1 usado para escrever os artigos.<\/p>\r\n
Reserve um tempo para descobrir quem \u00e9 a pessoa mais adequada para escrever diferentes t\u00f3picos de sua documenta\u00e7\u00e3o t\u00e9cnica e entre em contato com ela para atribuir-lhe a tarefa. Voc\u00ea tamb\u00e9m pode realizar entrevistas com seus especialistas e escrever o conte\u00fado voc\u00ea mesmo.<\/p>\r\n
Mantenha registros detalhados dos t\u00f3picos e da pessoa respons\u00e1vel por fornecer o conte\u00fado e acompanhe o est\u00e1gio em que o conte\u00fado se encontra.<\/p>\r\n
Projete modelos e organize o conte\u00fado<\/strong><\/h3>\r\nEmbora a parte mais importante da sua documenta\u00e7\u00e3o seja o conte\u00fado escrito, tamb\u00e9m \u00e9 uma boa ideia considerar a apar\u00eancia visual dos documentos para o usu\u00e1rio final. O objetivo \u00e9 ter um site de documenta\u00e7\u00e3o bem organizado e visualmente atraente, em vez de um amontoado de anota\u00e7\u00f5es mal projetadas que n\u00e3o ajudam ningu\u00e9m.<\/p>\r\n
Ao pensar no design da documenta\u00e7\u00e3o, considere a estrutura e a navega\u00e7\u00e3o do seu conte\u00fado. Seus usu\u00e1rios geralmente recorrem \u00e0 documenta\u00e7\u00e3o t\u00e9cnica para encontrar informa\u00e7\u00f5es espec\u00edficas ou uma solu\u00e7\u00e3o para um problema, portanto, sua pesquisa deve permitir que eles realizem essa tarefa rapidamente.<\/p>\r\n
Lembre-se de colocar suas informa\u00e7\u00f5es em categorias e subcategorias que os usu\u00e1rios possam pesquisar com efici\u00eancia. O ideal \u00e9 que voc\u00ea tenha uma barra de pesquisa que os usu\u00e1rios possam usar para acessar instantaneamente as informa\u00e7\u00f5es que est\u00e3o procurando.<\/p>\r\n
Comece com a cria\u00e7\u00e3o de conte\u00fado<\/strong><\/h3>\r\nVoc\u00ea j\u00e1 deve ter dado o pontap\u00e9 inicial no processo de reda\u00e7\u00e3o com a pesquisa de documenta\u00e7\u00e3o e a colabora\u00e7\u00e3o com os especialistas. Escrever documenta\u00e7\u00e3o t\u00e9cnica \u00e9 um trabalho de equipe e voc\u00ea ter\u00e1 muitos colaboradores participando desse processo colaborativo.<\/p>\r\n
Se ainda n\u00e3o o fez, re\u00fana-se com a equipe e delegue as tarefas de conte\u00fado ao membro mais adequado com base em suas habilidades. A melhor documenta\u00e7\u00e3o \u00e9 produzida quando os redatores come\u00e7am com esbo\u00e7os e direcionam sua documenta\u00e7\u00e3o para um usu\u00e1rio espec\u00edfico.<\/p>\r\n
Sua documenta\u00e7\u00e3o deve come\u00e7ar com um esbo\u00e7o de alto n\u00edvel<\/a> para cada um dos t\u00f3picos que planeja abordar. Re\u00fana o restante do conte\u00fado necess\u00e1rio para sua pe\u00e7a de conte\u00fado, juntamente com todos os recursos visuais de apoio.<\/p>\r\nLembre-se de escrever em linguagem simples e clara que seja facilmente compreens\u00edvel para o usu\u00e1rio. N\u00e3o presuma que os leitores t\u00eam o mesmo n\u00edvel de conhecimento pr\u00e9vio que voc\u00ea – inclua o m\u00e1ximo de contexto poss\u00edvel para ajudar na compreens\u00e3o. Escreva a quantidade de conte\u00fado necess\u00e1ria para transmitir seu ponto de vista e nem uma palavra a mais – menos \u00e9 definitivamente melhor quando se trata de documenta\u00e7\u00e3o.<\/p>\r\n
Revise e colabore com a sua equipe<\/strong><\/h3>\r\nDepois de come\u00e7ar a trabalhar no conte\u00fado, voc\u00ea precisar\u00e1 chamar especialistas para revisar a precis\u00e3o do conte\u00fado. Chame-os logo ap\u00f3s o primeiro rascunho e ap\u00f3s o rascunho final para dar feedback sobre sua documenta\u00e7\u00e3o. Ap\u00f3s o primeiro rascunho, voc\u00ea deve receber feedback sobre o esbo\u00e7o geral e o fluxo do documento, em vez de feedback sobre erros de digita\u00e7\u00e3o e gram\u00e1tica. Somente ap\u00f3s a revis\u00e3o final \u00e9 que voc\u00ea deseja receber cr\u00edticas detalhadas sobre a forma como redigiu o conte\u00fado.<\/p>\r\n
Procure revis\u00f5es por pares com outros membros da sua equipe que possam testar a usabilidade da sua documenta\u00e7\u00e3o t\u00e9cnica. Pe\u00e7a a outra pessoa que examine a documenta\u00e7\u00e3o e registre as \u00e1reas em que ela se perdeu ou ficou confusa. Depois de receber o feedback da revis\u00e3o por pares, incorpore as altera\u00e7\u00f5es em sua documenta\u00e7\u00e3o.<\/p>\r\n
Al\u00e9m disso, confira o nosso artigo sobre Como testar a usabilidade dos documentos t\u00e9cnicos<\/em><\/strong><\/p>\r\nPublicar o conte\u00fado<\/strong><\/h3>\r\nAp\u00f3s ter analisado seu conte\u00fado v\u00e1rias vezes, \u00e9 hora de publicar sua documenta\u00e7\u00e3o pronta para seu p\u00fablico. Quando a sua documenta\u00e7\u00e3o estiver ativa v\u00e1 para verificar se h\u00e1 atualiza\u00e7\u00f5es de \u00faltima hora e certifique-se de que isso \u00e9 livre de erros.<\/p>\r\n
Ao publicar seu conte\u00fado, talvez voc\u00ea queira usar um software de base de conhecimento como o Document360, que \u00e9 uma boa maneira de hospedar sua documenta\u00e7\u00e3o. Ele vem com arquitetura de informa\u00e7\u00f5es e organiza\u00e7\u00e3o de categorias incorporadas, al\u00e9m de uma barra de pesquisa proeminente e capacidade de resposta m\u00f3vel.<\/p>\r\n
\r\n\r\nUm software intuitivo de base de conhecimento para adicionar facilmente seu conte\u00fado e integr\u00e1-lo a qualquer aplicativo. Tente com o Document360<\/p>\r\nComece Agora<\/a><\/div>\r\n![\"Documento360\"](\"https:\/\/document360.com\/wp-content\/themes\/document360\/images\/blog-call-to-action.png\")
<\/div>\r\n<\/div>\r\nDepois que o site estiver no ar, talvez voc\u00ea queira realizar mais testes sobre a efic\u00e1cia da documenta\u00e7\u00e3o, coletando feedback dos usu\u00e1rios. Fa\u00e7a uma auditoria da navega\u00e7\u00e3o da sua documenta\u00e7\u00e3o para verificar se os usu\u00e1rios podem navegar facilmente e encontrar o que est\u00e3o procurando – identifique coisas como links quebrados e se os elementos de navega\u00e7\u00e3o est\u00e3o funcionando corretamente.<\/p>\r\n
Atualizar e gerenciar a documenta\u00e7\u00e3o baseada no analytics<\/strong><\/h3>\r\nSua documenta\u00e7\u00e3o t\u00e9cnica nunca est\u00e1 pronta. Se voc\u00ea estiver usando o software apropriado, voc\u00ea ter\u00e1 an\u00e1lises que podem ser revisadas que mostram a efic\u00e1cia do seu conte\u00fado. Voc\u00ea deveria estar sempre revisando sua documenta\u00e7\u00e3o para atualiza\u00e7\u00f5es e evitar deix\u00e1-la ficar parada.<\/p>\r\n
Voc\u00ea precisa manter sua documenta\u00e7\u00e3o alinhada com as novas atualiza\u00e7\u00f5es e vers\u00f5es de produtos Agende uma manuten\u00e7\u00e3o regular para seu conte\u00fado com base em dicas que voc\u00ea colhe das suas an\u00e1lises, como pesquisas falhadas ou classifica\u00e7\u00f5es negativas de artigos.<\/p>\r\n
Se voc\u00ea usar o software correto, pode salvar vers\u00f5es anteriores da sua documenta\u00e7\u00e3o, caso precise revert\u00ea-lo mais tarde.<\/p>\r\n
O que fazer e o que n\u00e3o fazer na documenta\u00e7\u00e3o t\u00e9cnica<\/strong><\/h2>\r\nFazer<\/strong><\/h3>\r\n\r\n\t- Mantenha a simplicidade e a clareza – n\u00e3o complique demais a documenta\u00e7\u00e3o nem use linguagem complexa.<\/li>\r\n\t
- Tenha sempre o usu\u00e1rio em mente – sempre que escrever uma documenta\u00e7\u00e3o, certifique-se de que est\u00e1 claro para quem ela se destina.<\/li>\r\n\t
- Torne-a visual – se puder representar o que est\u00e1 tentando transmitir com uma imagem, fa\u00e7a isso.<\/li>\r\n\t
- Passe por um processo de revis\u00e3o completo – se poss\u00edvel, certifique-se de que v\u00e1rias pessoas revisem seu trabalho durante a fase de reda\u00e7\u00e3o.<\/li>\r\n<\/ul>\r\n
N\u00e3o fazer:<\/strong><\/h3>\r\n\r\n\t- Supor que o p\u00fablico esteja familiarizado com o assunto – sempre forne\u00e7a o m\u00e1ximo de contexto poss\u00edvel.<\/li>\r\n\t
- Usar uma voz passiva – sempre use a voz ativa: \u201cEle apertou o bot\u00e3o\u201d em vez de \u2018o bot\u00e3o foi apertado por ele\u2019.<\/li>\r\n\t
- Usar acr\u00f4nimos – se precisar usar acr\u00f4nimos, indique claramente o significado do acr\u00f4nimo ao lado dele.<\/li>\r\n\t
- Tentar ser engra\u00e7ado – o que pode ser divertido para voc\u00ea pode ser insultante ou ofensivo para seus leitores.<\/li>\r\n<\/ul>\r\n
Tamb\u00e9m Leia:<\/strong> Como escrever documenta\u00e7\u00e3o inclusiva?<\/p>\r\nPensamentos finais<\/strong><\/h2>\r\nN\u00e3o cometa o erro de subestimar a import\u00e2ncia da documenta\u00e7\u00e3o t\u00e9cnica para o sucesso geral de sua empresa. Ela \u00e9 uma parte essencial da comunica\u00e7\u00e3o e significa que os membros da sua equipe n\u00e3o precisam estar literalmente dispon\u00edveis toda vez que algu\u00e9m tiver uma d\u00favida, seja um cliente ou uma parte interessada da sua equipe.<\/p>\r\n
N\u00e3o \u00e9 necess\u00e1rio abordar a documenta\u00e7\u00e3o t\u00e9cnica com pesar – se voc\u00ea seguir as etapas que descrevemos neste guia, estar\u00e1 no caminho certo para criar conte\u00fado \u00fatil para seus usu\u00e1rios. Eles ter\u00e3o a capacidade de usar seu produto e se divertir\u00e3o mais com ele, o que \u00e9 exatamente o objetivo da documenta\u00e7\u00e3o t\u00e9cnica.<\/p>\r\n
\r\n\r\nInteressado na base de conhecimento do Document360? Agende uma demonstra\u00e7\u00e3o com um de nossos especialistas.<\/p>\r\nReserve uma demonstra\u00e7\u00e3o<\/a><\/div>\r\n<\/div>\r\n<\/div>\r\n\r\n\r\n\r\nPerguntas Frequentes<\/h2>\r\n\r\n\t- \r\n
Como a documenta\u00e7\u00e3o t\u00e9cnica \u00e9 diferente da documenta\u00e7\u00e3o do usu\u00e1rio? <\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o t\u00e9cnica \u00e9 a documenta\u00e7\u00e3o que descreve como um produto ou servi\u00e7o funciona. Ela \u00e9 mais voltada para o desenvolvedor e criada para descrever (em linguagem t\u00e9cnica) o uso, a funcionalidade ou a arquitetura de um produto, sistema ou servi\u00e7o. A documenta\u00e7\u00e3o de um produto ou servi\u00e7o entregue aos usu\u00e1rios finais \u00e9 chamada de documenta\u00e7\u00e3o do usu\u00e1rio. A documenta\u00e7\u00e3o do usu\u00e1rio tem o objetivo de ajudar os usu\u00e1rios finais a entender e usar o produto ou servi\u00e7o.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t
- \r\n
Diferen\u00e7a entre documenta\u00e7\u00e3o de processos e produtos?<\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o pode ser de dois tipos: produtos e processos. A documenta\u00e7\u00e3o do produto define o produto em desenvolvimento e fornece instru\u00e7\u00f5es sobre como us\u00e1-lo. A documenta\u00e7\u00e3o do processo, por outro lado, refere-se a todo o conte\u00fado produzido durante o processo de desenvolvimento.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t
- \r\n
O que \u00e9 documenta\u00e7\u00e3o t\u00e9cnica de software? <\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o t\u00e9cnica do software define as v\u00e1rias rotas e pontos de extremidade da API que o desenvolvedor pode acessar ou pode explicar as bibliotecas, as integra\u00e7\u00f5es e as depend\u00eancias do SDK. Todos os engenheiros que j\u00e1 escreveram c\u00f3digos em qualquer linguagem, em algum momento, fizeram refer\u00eancia \u00e0 documenta\u00e7\u00e3o t\u00e9cnica.<\/p>\r\n<\/div>\r\n<\/li>\r\n<\/ul>\r\n<\/div>\r\n
Ele descreve os recursos e a funcionalidade do produto de forma clara para que qualquer pessoa possa us\u00e1-lo. O objetivo principal \u00e9 explicar um aspecto espec\u00edfico do produto para o p\u00fablico-alvo. Embora seja apresentada de v\u00e1rias formas diferentes, a maior parte da documenta\u00e7\u00e3o t\u00e9cnica \u00e9 publicada on-line e normalmente \u00e9 escrita por redatores t\u00e9cnicos, desenvolvedores e gerentes de projeto.<\/p>\r\n
A documenta\u00e7\u00e3o t\u00e9cnica deve ser clara, concisa, precisa e na verdade resolver um problema para seus usu\u00e1rios.<\/p>\r\n
Import\u00e2ncia da documenta\u00e7\u00e3o t\u00e9cnica<\/strong><\/h2>\r\nA documenta\u00e7\u00e3o t\u00e9cnica \u00e9 de vital import\u00e2ncia para a sua empresa de software. Aqui est\u00e3o algumas raz\u00f5es.<\/p>\r\n
Permite a tomada de decis\u00e3o r\u00e1pida pela equipe do produto<\/strong><\/h3>\r\nQuando sua equipe de produtos tem acesso \u00e0 documenta\u00e7\u00e3o t\u00e9cnica correta, eles podem tomar decis\u00f5es muito mais r\u00e1pidas. Eles n\u00e3o t\u00eam que voltar a navegar por e-mails ou t\u00f3picos nas ferramentas de colabora\u00e7\u00e3o \u2014 podem em vez disso consultar instantaneamente os documentos produzidos ao lado do software que explica como tudo funciona e registra o racioc\u00ednio por tr\u00e1s das decis\u00f5es.<\/p>\r\n
Ajuda contextual para usu\u00e1rios<\/strong><\/h3>\r\nQuando os clientes estiverem usando o software, eles poder\u00e3o acessar a documenta\u00e7\u00e3o t\u00e9cnica junto com o produto para obter ajuda no uso da ferramenta. A documenta\u00e7\u00e3o pode ser exibida no aplicativo para que os clientes n\u00e3o precisem mudar de contexto quando tiverem problemas. Isso melhora a usabilidade e a experi\u00eancia gerais do seu produto de software.<\/p>\r\n
Ter uma documenta\u00e7\u00e3o t\u00e9cnica robusta facilita a divulga\u00e7\u00e3o de seu produto para clientes em potencial. Muitos clientes poder\u00e3o pesquisar detalhadamente como o seu produto funciona, e a documenta\u00e7\u00e3o t\u00e9cnica poder\u00e1 explicar os recursos do seu software com mais profundidade do que os materiais de marketing comuns.<\/p>\r\n
Reduz chamadas de suporte t\u00e9cnico<\/strong><\/h3>\r\nQuando voc\u00ea tem uma documenta\u00e7\u00e3o t\u00e9cnica abrangente, os clientes podem consultar os documentos quando tiverem problemas t\u00e9cnicos. Isso reduz o n\u00famero de chamadas recebidas na sua fila de suporte t\u00e9cnico e significa que voc\u00ea pode dar suporte a mais clientes com um or\u00e7amento menor. A maioria dos clientes prefere solucionar os problemas por conta pr\u00f3pria em vez de ficar esperando que uma pessoa os ajude.<\/p>\r\n
Registra ideias de desenvolvedores<\/strong><\/h3>\r\nA documenta\u00e7\u00e3o do seu software pode registrar as ideias que os desenvolvedores t\u00eam em rela\u00e7\u00e3o ao seu produto de software. Mesmo que voc\u00ea n\u00e3o as implemente imediatamente, mais adiante voc\u00ea poder\u00e1 procurar recursos que talvez queira considerar ou outras altera\u00e7\u00f5es que queira fazer. Os desenvolvedores n\u00e3o necessariamente se lembram de suas ideias mais tarde, portanto, sua documenta\u00e7\u00e3o \u00e9 um bom lugar para manter um registro.<\/p>\r\n
Fornece um roteiro para projetos futuros<\/strong><\/h3>\r\nSua documenta\u00e7\u00e3o t\u00e9cnica \u00e9 um roteiro para os projetos que voc\u00ea deseja desenvolver no futuro, registrando os planos que voc\u00ea tem para o desenvolvimento do seu produto e os novos recursos que est\u00e3o sendo preparados. Ela garante que todos na sua equipe estejam na mesma p\u00e1gina e trabalhando para atingir um \u00fanico objetivo.<\/p>\r\n
Melhora a comunica\u00e7\u00e3o com interessados e desenvolvedores<\/strong><\/h3>\r\nA documenta\u00e7\u00e3o \u00e9 uma forma importante de comunica\u00e7\u00e3o – as partes interessadas e os desenvolvedores n\u00e3o precisam conversar diretamente entre si para acessar informa\u00e7\u00f5es sobre o software. A documenta\u00e7\u00e3o salva o conhecimento para a posteridade e permite que a equipe analise o trabalho que foi conclu\u00eddo anteriormente para informar as decis\u00f5es futuras.<\/p>\r\n
Tipos de documenta\u00e7\u00e3o t\u00e9cnica com exemplos<\/strong><\/h2>\r\nExistem muitos tipos diferentes de documenta\u00e7\u00e3o t\u00e9cnica \u2013 passaremos por eles agora.<\/p>\r\n
Documenta\u00e7\u00e3o t\u00e9cnica no SDLC<\/strong><\/h3>\r\nEsta \u00e9 a documenta\u00e7\u00e3o de software nos bastidores destinada aos seus desenvolvedores e outros membros da equipe.<\/p>\r\n
Documenta\u00e7\u00e3o do administrador do sistema<\/strong> – melhora \u00e9 v\u00e1lida a seguran\u00e7a, documentando os detalhes e procedimentos da configura\u00e7\u00e3o que sustentam uma pol\u00edtica de seguran\u00e7a. Eles cobrem instala\u00e7\u00f5es e atualiza\u00e7\u00f5es que auxiliam um administrador do sistema com a manuten\u00e7\u00e3o de produtos.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o de exig\u00eancia de produto<\/strong> \u2013 fornece um \u00fanico ponto de refer\u00eancia para os requisitos de entrada de design t\u00e9cnico de um produto e explica como o produto deve funcionar para atender \u00e0s necessidades dos clientes.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o de design de experi\u00eancia do usu\u00e1rio<\/strong> – um documento de trabalho de um produto desde sua concep\u00e7\u00e3o at\u00e9 a vers\u00e3o atual, e eles incluem modelos de conte\u00fado, mapas de empatia, mapas de experi\u00eancia, modelos mentais e pessoas.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do c\u00f3digo-fonte<\/strong> \u2013 documenta\u00e7\u00e3o do software que garante que seu c\u00f3digo seja leg\u00edvel, possa ser compreendido rapidamente e seja f\u00e1cil de manter pelos desenvolvedores. Inclui coment\u00e1rios de c\u00f3digo que podem explicar partes de c\u00f3digo que n\u00e3o s\u00e3o \u00f3bvias.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o da API<\/strong> <\/a>\u2013 permite que desenvolvedores trabalhem com a sua API e mostra se o seu software vai ou n\u00e3o resolver o problema deles.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do guia de manuten\u00e7\u00e3o<\/strong> \u2013 diga ao usu\u00e1rio como manter o sistema de forma eficaz e pode incluir uma defini\u00e7\u00e3o do ambiente de suporte ao software. fun\u00e7\u00f5es e responsabilidades do pessoal de manuten\u00e7\u00e3o.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do produto<\/h3>\r\n
Base de conhecimento de produtos<\/strong> \u2013 uma biblioteca de informa\u00e7\u00f5es sobre o produto do seu software que cont\u00e9m respostas para clientes procurando resolver problemas sozinhos.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nManual do usu\u00e1rio<\/strong><\/a> – cont\u00e9m extensas informa\u00e7\u00f5es sobre como instalar e operar o produto, listando requisitos de hardware e software, explica\u00e7\u00e3o completa dos recursos do produto e como us\u00e1-los em toda a sua extens\u00e3o.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do projeto<\/a> – registra os principais detalhes do projeto e produz os documentos necess\u00e1rios para implementar um projeto com sucesso. Ele pode incluir propostas de projeto<\/a>, documentos de requisitos de neg\u00f3cios<\/a>, casos de neg\u00f3cios, planos de projeto e relat\u00f3rios de status do projeto.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/p>\r\n
8 etapas para criar uma incr\u00edvel documenta\u00e7\u00e3o t\u00e9cnica<\/h2>\r\n
Aqui est\u00e3o as etapas que voc\u00ea precisa percorrer para criar uma documenta\u00e7\u00e3o t\u00e9cnica que seja bem sucedida e \u00fatil para seus usu\u00e1rios.<\/p>\r\n
Decida o tipo de p\u00fablico e o tipo de documenta\u00e7\u00e3o<\/h3>\r\n
Antes de mais nada, voc\u00ea precisa conhecer o p\u00fablico-alvo da sua documenta\u00e7\u00e3o. S\u00e3o os seus clientes, outros desenvolvedores, a equipe de produtos ou qualquer outra parte interessada? Ao saber quem \u00e9 o seu p\u00fablico, voc\u00ea poder\u00e1 adaptar o tom e o estilo da sua documenta\u00e7\u00e3o para torn\u00e1-la mais relevante e envolvente.
\r\nSe voc\u00ea n\u00e3o souber quem \u00e9 o seu p\u00fablico, sua documenta\u00e7\u00e3o n\u00e3o ter\u00e1 foco e n\u00e3o ser\u00e1 \u00fatil. Definir o p\u00fablico-alvo no est\u00e1gio inicial do processo de documenta\u00e7\u00e3o ajudar\u00e1 na cria\u00e7\u00e3o do documento e garantir\u00e1 que voc\u00ea tenha um alvo claramente definido.<\/p>\r\n
Pesquisa de t\u00f3picos<\/strong><\/h3>\r\nDepois de definir o p\u00fablico-alvo, voc\u00ea precisa pesquisar os t\u00f3picos que abordar\u00e1 em sua documenta\u00e7\u00e3o. Voc\u00ea n\u00e3o pode esperar escrever um conte\u00fado t\u00e9cnico eficaz se n\u00e3o tiver uma ideia clara dos t\u00f3picos sobre os quais escrever\u00e1. Nesse est\u00e1gio, \u00e9 uma boa ideia trabalhar com a sua equipe para fazer um brainstorming de diferentes t\u00f3picos e atribuir v\u00e1rias tarefas de pesquisa a diferentes membros da equipe.<\/p>\r\n
\u00c9 importante fazer perguntas a si mesmo:<\/p>\r\n
\r\n\t- Quais \u00e1reas queremos que nossa documenta\u00e7\u00e3o t\u00e9cnica inclua?<\/li>\r\n\t
- Qual \u00e9 o objetivo que queremos alcan\u00e7ar com nossa documenta\u00e7\u00e3o t\u00e9cnica?<\/li>\r\n\t
- J\u00e1 temos alguma documenta\u00e7\u00e3o existente com a qual podemos trabalhar?<\/li>\r\n<\/ul>\r\n
Certifique-se de que se trata de um esfor\u00e7o em equipe para pesquisar os t\u00f3picos \u2013 voc\u00ea n\u00e3o precisa ir sozinho.<\/p>\r\n
Capturar conhecimento<\/strong><\/h3>\r\nAo escrever sua documenta\u00e7\u00e3o, \u00e9 prov\u00e1vel que voc\u00ea n\u00e3o seja o \u00fanico autor. Ser\u00e1 necess\u00e1rio colaborar com outras partes interessadas da sua equipe para produzir a documenta\u00e7\u00e3o t\u00e9cnica. Nesse est\u00e1gio, voc\u00ea precisa trabalhar com especialistas no assunto para obter o conhecimento que ser\u00e1 usado para escrever os artigos.<\/p>\r\n
Reserve um tempo para descobrir quem \u00e9 a pessoa mais adequada para escrever diferentes t\u00f3picos de sua documenta\u00e7\u00e3o t\u00e9cnica e entre em contato com ela para atribuir-lhe a tarefa. Voc\u00ea tamb\u00e9m pode realizar entrevistas com seus especialistas e escrever o conte\u00fado voc\u00ea mesmo.<\/p>\r\n
Mantenha registros detalhados dos t\u00f3picos e da pessoa respons\u00e1vel por fornecer o conte\u00fado e acompanhe o est\u00e1gio em que o conte\u00fado se encontra.<\/p>\r\n
Projete modelos e organize o conte\u00fado<\/strong><\/h3>\r\nEmbora a parte mais importante da sua documenta\u00e7\u00e3o seja o conte\u00fado escrito, tamb\u00e9m \u00e9 uma boa ideia considerar a apar\u00eancia visual dos documentos para o usu\u00e1rio final. O objetivo \u00e9 ter um site de documenta\u00e7\u00e3o bem organizado e visualmente atraente, em vez de um amontoado de anota\u00e7\u00f5es mal projetadas que n\u00e3o ajudam ningu\u00e9m.<\/p>\r\n
Ao pensar no design da documenta\u00e7\u00e3o, considere a estrutura e a navega\u00e7\u00e3o do seu conte\u00fado. Seus usu\u00e1rios geralmente recorrem \u00e0 documenta\u00e7\u00e3o t\u00e9cnica para encontrar informa\u00e7\u00f5es espec\u00edficas ou uma solu\u00e7\u00e3o para um problema, portanto, sua pesquisa deve permitir que eles realizem essa tarefa rapidamente.<\/p>\r\n
Lembre-se de colocar suas informa\u00e7\u00f5es em categorias e subcategorias que os usu\u00e1rios possam pesquisar com efici\u00eancia. O ideal \u00e9 que voc\u00ea tenha uma barra de pesquisa que os usu\u00e1rios possam usar para acessar instantaneamente as informa\u00e7\u00f5es que est\u00e3o procurando.<\/p>\r\n
Comece com a cria\u00e7\u00e3o de conte\u00fado<\/strong><\/h3>\r\nVoc\u00ea j\u00e1 deve ter dado o pontap\u00e9 inicial no processo de reda\u00e7\u00e3o com a pesquisa de documenta\u00e7\u00e3o e a colabora\u00e7\u00e3o com os especialistas. Escrever documenta\u00e7\u00e3o t\u00e9cnica \u00e9 um trabalho de equipe e voc\u00ea ter\u00e1 muitos colaboradores participando desse processo colaborativo.<\/p>\r\n
Se ainda n\u00e3o o fez, re\u00fana-se com a equipe e delegue as tarefas de conte\u00fado ao membro mais adequado com base em suas habilidades. A melhor documenta\u00e7\u00e3o \u00e9 produzida quando os redatores come\u00e7am com esbo\u00e7os e direcionam sua documenta\u00e7\u00e3o para um usu\u00e1rio espec\u00edfico.<\/p>\r\n
Sua documenta\u00e7\u00e3o deve come\u00e7ar com um esbo\u00e7o de alto n\u00edvel<\/a> para cada um dos t\u00f3picos que planeja abordar. Re\u00fana o restante do conte\u00fado necess\u00e1rio para sua pe\u00e7a de conte\u00fado, juntamente com todos os recursos visuais de apoio.<\/p>\r\nLembre-se de escrever em linguagem simples e clara que seja facilmente compreens\u00edvel para o usu\u00e1rio. N\u00e3o presuma que os leitores t\u00eam o mesmo n\u00edvel de conhecimento pr\u00e9vio que voc\u00ea – inclua o m\u00e1ximo de contexto poss\u00edvel para ajudar na compreens\u00e3o. Escreva a quantidade de conte\u00fado necess\u00e1ria para transmitir seu ponto de vista e nem uma palavra a mais – menos \u00e9 definitivamente melhor quando se trata de documenta\u00e7\u00e3o.<\/p>\r\n
Revise e colabore com a sua equipe<\/strong><\/h3>\r\nDepois de come\u00e7ar a trabalhar no conte\u00fado, voc\u00ea precisar\u00e1 chamar especialistas para revisar a precis\u00e3o do conte\u00fado. Chame-os logo ap\u00f3s o primeiro rascunho e ap\u00f3s o rascunho final para dar feedback sobre sua documenta\u00e7\u00e3o. Ap\u00f3s o primeiro rascunho, voc\u00ea deve receber feedback sobre o esbo\u00e7o geral e o fluxo do documento, em vez de feedback sobre erros de digita\u00e7\u00e3o e gram\u00e1tica. Somente ap\u00f3s a revis\u00e3o final \u00e9 que voc\u00ea deseja receber cr\u00edticas detalhadas sobre a forma como redigiu o conte\u00fado.<\/p>\r\n
Procure revis\u00f5es por pares com outros membros da sua equipe que possam testar a usabilidade da sua documenta\u00e7\u00e3o t\u00e9cnica. Pe\u00e7a a outra pessoa que examine a documenta\u00e7\u00e3o e registre as \u00e1reas em que ela se perdeu ou ficou confusa. Depois de receber o feedback da revis\u00e3o por pares, incorpore as altera\u00e7\u00f5es em sua documenta\u00e7\u00e3o.<\/p>\r\n
Al\u00e9m disso, confira o nosso artigo sobre Como testar a usabilidade dos documentos t\u00e9cnicos<\/em><\/strong><\/p>\r\nPublicar o conte\u00fado<\/strong><\/h3>\r\nAp\u00f3s ter analisado seu conte\u00fado v\u00e1rias vezes, \u00e9 hora de publicar sua documenta\u00e7\u00e3o pronta para seu p\u00fablico. Quando a sua documenta\u00e7\u00e3o estiver ativa v\u00e1 para verificar se h\u00e1 atualiza\u00e7\u00f5es de \u00faltima hora e certifique-se de que isso \u00e9 livre de erros.<\/p>\r\n
Ao publicar seu conte\u00fado, talvez voc\u00ea queira usar um software de base de conhecimento como o Document360, que \u00e9 uma boa maneira de hospedar sua documenta\u00e7\u00e3o. Ele vem com arquitetura de informa\u00e7\u00f5es e organiza\u00e7\u00e3o de categorias incorporadas, al\u00e9m de uma barra de pesquisa proeminente e capacidade de resposta m\u00f3vel.<\/p>\r\n
\r\n\r\nUm software intuitivo de base de conhecimento para adicionar facilmente seu conte\u00fado e integr\u00e1-lo a qualquer aplicativo. Tente com o Document360<\/p>\r\nComece Agora<\/a><\/div>\r\n<\/div>\r\n<\/div>\r\nDepois que o site estiver no ar, talvez voc\u00ea queira realizar mais testes sobre a efic\u00e1cia da documenta\u00e7\u00e3o, coletando feedback dos usu\u00e1rios. Fa\u00e7a uma auditoria da navega\u00e7\u00e3o da sua documenta\u00e7\u00e3o para verificar se os usu\u00e1rios podem navegar facilmente e encontrar o que est\u00e3o procurando – identifique coisas como links quebrados e se os elementos de navega\u00e7\u00e3o est\u00e3o funcionando corretamente.<\/p>\r\n
Atualizar e gerenciar a documenta\u00e7\u00e3o baseada no analytics<\/strong><\/h3>\r\nSua documenta\u00e7\u00e3o t\u00e9cnica nunca est\u00e1 pronta. Se voc\u00ea estiver usando o software apropriado, voc\u00ea ter\u00e1 an\u00e1lises que podem ser revisadas que mostram a efic\u00e1cia do seu conte\u00fado. Voc\u00ea deveria estar sempre revisando sua documenta\u00e7\u00e3o para atualiza\u00e7\u00f5es e evitar deix\u00e1-la ficar parada.<\/p>\r\n
Voc\u00ea precisa manter sua documenta\u00e7\u00e3o alinhada com as novas atualiza\u00e7\u00f5es e vers\u00f5es de produtos Agende uma manuten\u00e7\u00e3o regular para seu conte\u00fado com base em dicas que voc\u00ea colhe das suas an\u00e1lises, como pesquisas falhadas ou classifica\u00e7\u00f5es negativas de artigos.<\/p>\r\n
Se voc\u00ea usar o software correto, pode salvar vers\u00f5es anteriores da sua documenta\u00e7\u00e3o, caso precise revert\u00ea-lo mais tarde.<\/p>\r\n
O que fazer e o que n\u00e3o fazer na documenta\u00e7\u00e3o t\u00e9cnica<\/strong><\/h2>\r\nFazer<\/strong><\/h3>\r\n\r\n\t- Mantenha a simplicidade e a clareza – n\u00e3o complique demais a documenta\u00e7\u00e3o nem use linguagem complexa.<\/li>\r\n\t
- Tenha sempre o usu\u00e1rio em mente – sempre que escrever uma documenta\u00e7\u00e3o, certifique-se de que est\u00e1 claro para quem ela se destina.<\/li>\r\n\t
- Torne-a visual – se puder representar o que est\u00e1 tentando transmitir com uma imagem, fa\u00e7a isso.<\/li>\r\n\t
- Passe por um processo de revis\u00e3o completo – se poss\u00edvel, certifique-se de que v\u00e1rias pessoas revisem seu trabalho durante a fase de reda\u00e7\u00e3o.<\/li>\r\n<\/ul>\r\n
N\u00e3o fazer:<\/strong><\/h3>\r\n\r\n\t- Supor que o p\u00fablico esteja familiarizado com o assunto – sempre forne\u00e7a o m\u00e1ximo de contexto poss\u00edvel.<\/li>\r\n\t
- Usar uma voz passiva – sempre use a voz ativa: \u201cEle apertou o bot\u00e3o\u201d em vez de \u2018o bot\u00e3o foi apertado por ele\u2019.<\/li>\r\n\t
- Usar acr\u00f4nimos – se precisar usar acr\u00f4nimos, indique claramente o significado do acr\u00f4nimo ao lado dele.<\/li>\r\n\t
- Tentar ser engra\u00e7ado – o que pode ser divertido para voc\u00ea pode ser insultante ou ofensivo para seus leitores.<\/li>\r\n<\/ul>\r\n
Tamb\u00e9m Leia:<\/strong> Como escrever documenta\u00e7\u00e3o inclusiva?<\/p>\r\nPensamentos finais<\/strong><\/h2>\r\nN\u00e3o cometa o erro de subestimar a import\u00e2ncia da documenta\u00e7\u00e3o t\u00e9cnica para o sucesso geral de sua empresa. Ela \u00e9 uma parte essencial da comunica\u00e7\u00e3o e significa que os membros da sua equipe n\u00e3o precisam estar literalmente dispon\u00edveis toda vez que algu\u00e9m tiver uma d\u00favida, seja um cliente ou uma parte interessada da sua equipe.<\/p>\r\n
N\u00e3o \u00e9 necess\u00e1rio abordar a documenta\u00e7\u00e3o t\u00e9cnica com pesar – se voc\u00ea seguir as etapas que descrevemos neste guia, estar\u00e1 no caminho certo para criar conte\u00fado \u00fatil para seus usu\u00e1rios. Eles ter\u00e3o a capacidade de usar seu produto e se divertir\u00e3o mais com ele, o que \u00e9 exatamente o objetivo da documenta\u00e7\u00e3o t\u00e9cnica.<\/p>\r\n
\r\n\r\nInteressado na base de conhecimento do Document360? Agende uma demonstra\u00e7\u00e3o com um de nossos especialistas.<\/p>\r\nReserve uma demonstra\u00e7\u00e3o<\/a><\/div>\r\n<\/div>\r\n<\/div>\r\n\r\n\r\n\r\nPerguntas Frequentes<\/h2>\r\n\r\n\t- \r\n
Como a documenta\u00e7\u00e3o t\u00e9cnica \u00e9 diferente da documenta\u00e7\u00e3o do usu\u00e1rio? <\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o t\u00e9cnica \u00e9 a documenta\u00e7\u00e3o que descreve como um produto ou servi\u00e7o funciona. Ela \u00e9 mais voltada para o desenvolvedor e criada para descrever (em linguagem t\u00e9cnica) o uso, a funcionalidade ou a arquitetura de um produto, sistema ou servi\u00e7o. A documenta\u00e7\u00e3o de um produto ou servi\u00e7o entregue aos usu\u00e1rios finais \u00e9 chamada de documenta\u00e7\u00e3o do usu\u00e1rio. A documenta\u00e7\u00e3o do usu\u00e1rio tem o objetivo de ajudar os usu\u00e1rios finais a entender e usar o produto ou servi\u00e7o.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t
- \r\n
Diferen\u00e7a entre documenta\u00e7\u00e3o de processos e produtos?<\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o pode ser de dois tipos: produtos e processos. A documenta\u00e7\u00e3o do produto define o produto em desenvolvimento e fornece instru\u00e7\u00f5es sobre como us\u00e1-lo. A documenta\u00e7\u00e3o do processo, por outro lado, refere-se a todo o conte\u00fado produzido durante o processo de desenvolvimento.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t
- \r\n
O que \u00e9 documenta\u00e7\u00e3o t\u00e9cnica de software? <\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o t\u00e9cnica do software define as v\u00e1rias rotas e pontos de extremidade da API que o desenvolvedor pode acessar ou pode explicar as bibliotecas, as integra\u00e7\u00f5es e as depend\u00eancias do SDK. Todos os engenheiros que j\u00e1 escreveram c\u00f3digos em qualquer linguagem, em algum momento, fizeram refer\u00eancia \u00e0 documenta\u00e7\u00e3o t\u00e9cnica.<\/p>\r\n<\/div>\r\n<\/li>\r\n<\/ul>\r\n<\/div>\r\n
Quando sua equipe de produtos tem acesso \u00e0 documenta\u00e7\u00e3o t\u00e9cnica correta, eles podem tomar decis\u00f5es muito mais r\u00e1pidas. Eles n\u00e3o t\u00eam que voltar a navegar por e-mails ou t\u00f3picos nas ferramentas de colabora\u00e7\u00e3o \u2014 podem em vez disso consultar instantaneamente os documentos produzidos ao lado do software que explica como tudo funciona e registra o racioc\u00ednio por tr\u00e1s das decis\u00f5es.<\/p>\r\n
Ajuda contextual para usu\u00e1rios<\/strong><\/h3>\r\nQuando os clientes estiverem usando o software, eles poder\u00e3o acessar a documenta\u00e7\u00e3o t\u00e9cnica junto com o produto para obter ajuda no uso da ferramenta. A documenta\u00e7\u00e3o pode ser exibida no aplicativo para que os clientes n\u00e3o precisem mudar de contexto quando tiverem problemas. Isso melhora a usabilidade e a experi\u00eancia gerais do seu produto de software.<\/p>\r\n
Ter uma documenta\u00e7\u00e3o t\u00e9cnica robusta facilita a divulga\u00e7\u00e3o de seu produto para clientes em potencial. Muitos clientes poder\u00e3o pesquisar detalhadamente como o seu produto funciona, e a documenta\u00e7\u00e3o t\u00e9cnica poder\u00e1 explicar os recursos do seu software com mais profundidade do que os materiais de marketing comuns.<\/p>\r\n
Reduz chamadas de suporte t\u00e9cnico<\/strong><\/h3>\r\nQuando voc\u00ea tem uma documenta\u00e7\u00e3o t\u00e9cnica abrangente, os clientes podem consultar os documentos quando tiverem problemas t\u00e9cnicos. Isso reduz o n\u00famero de chamadas recebidas na sua fila de suporte t\u00e9cnico e significa que voc\u00ea pode dar suporte a mais clientes com um or\u00e7amento menor. A maioria dos clientes prefere solucionar os problemas por conta pr\u00f3pria em vez de ficar esperando que uma pessoa os ajude.<\/p>\r\n
Registra ideias de desenvolvedores<\/strong><\/h3>\r\nA documenta\u00e7\u00e3o do seu software pode registrar as ideias que os desenvolvedores t\u00eam em rela\u00e7\u00e3o ao seu produto de software. Mesmo que voc\u00ea n\u00e3o as implemente imediatamente, mais adiante voc\u00ea poder\u00e1 procurar recursos que talvez queira considerar ou outras altera\u00e7\u00f5es que queira fazer. Os desenvolvedores n\u00e3o necessariamente se lembram de suas ideias mais tarde, portanto, sua documenta\u00e7\u00e3o \u00e9 um bom lugar para manter um registro.<\/p>\r\n
Fornece um roteiro para projetos futuros<\/strong><\/h3>\r\nSua documenta\u00e7\u00e3o t\u00e9cnica \u00e9 um roteiro para os projetos que voc\u00ea deseja desenvolver no futuro, registrando os planos que voc\u00ea tem para o desenvolvimento do seu produto e os novos recursos que est\u00e3o sendo preparados. Ela garante que todos na sua equipe estejam na mesma p\u00e1gina e trabalhando para atingir um \u00fanico objetivo.<\/p>\r\n
Melhora a comunica\u00e7\u00e3o com interessados e desenvolvedores<\/strong><\/h3>\r\nA documenta\u00e7\u00e3o \u00e9 uma forma importante de comunica\u00e7\u00e3o – as partes interessadas e os desenvolvedores n\u00e3o precisam conversar diretamente entre si para acessar informa\u00e7\u00f5es sobre o software. A documenta\u00e7\u00e3o salva o conhecimento para a posteridade e permite que a equipe analise o trabalho que foi conclu\u00eddo anteriormente para informar as decis\u00f5es futuras.<\/p>\r\n
Tipos de documenta\u00e7\u00e3o t\u00e9cnica com exemplos<\/strong><\/h2>\r\nExistem muitos tipos diferentes de documenta\u00e7\u00e3o t\u00e9cnica \u2013 passaremos por eles agora.<\/p>\r\n
Documenta\u00e7\u00e3o t\u00e9cnica no SDLC<\/strong><\/h3>\r\nEsta \u00e9 a documenta\u00e7\u00e3o de software nos bastidores destinada aos seus desenvolvedores e outros membros da equipe.<\/p>\r\n
Documenta\u00e7\u00e3o do administrador do sistema<\/strong> – melhora \u00e9 v\u00e1lida a seguran\u00e7a, documentando os detalhes e procedimentos da configura\u00e7\u00e3o que sustentam uma pol\u00edtica de seguran\u00e7a. Eles cobrem instala\u00e7\u00f5es e atualiza\u00e7\u00f5es que auxiliam um administrador do sistema com a manuten\u00e7\u00e3o de produtos.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o de exig\u00eancia de produto<\/strong> \u2013 fornece um \u00fanico ponto de refer\u00eancia para os requisitos de entrada de design t\u00e9cnico de um produto e explica como o produto deve funcionar para atender \u00e0s necessidades dos clientes.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o de design de experi\u00eancia do usu\u00e1rio<\/strong> – um documento de trabalho de um produto desde sua concep\u00e7\u00e3o at\u00e9 a vers\u00e3o atual, e eles incluem modelos de conte\u00fado, mapas de empatia, mapas de experi\u00eancia, modelos mentais e pessoas.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do c\u00f3digo-fonte<\/strong> \u2013 documenta\u00e7\u00e3o do software que garante que seu c\u00f3digo seja leg\u00edvel, possa ser compreendido rapidamente e seja f\u00e1cil de manter pelos desenvolvedores. Inclui coment\u00e1rios de c\u00f3digo que podem explicar partes de c\u00f3digo que n\u00e3o s\u00e3o \u00f3bvias.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o da API<\/strong> <\/a>\u2013 permite que desenvolvedores trabalhem com a sua API e mostra se o seu software vai ou n\u00e3o resolver o problema deles.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do guia de manuten\u00e7\u00e3o<\/strong> \u2013 diga ao usu\u00e1rio como manter o sistema de forma eficaz e pode incluir uma defini\u00e7\u00e3o do ambiente de suporte ao software. fun\u00e7\u00f5es e responsabilidades do pessoal de manuten\u00e7\u00e3o.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do produto<\/h3>\r\n
Base de conhecimento de produtos<\/strong> \u2013 uma biblioteca de informa\u00e7\u00f5es sobre o produto do seu software que cont\u00e9m respostas para clientes procurando resolver problemas sozinhos.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nManual do usu\u00e1rio<\/strong><\/a> – cont\u00e9m extensas informa\u00e7\u00f5es sobre como instalar e operar o produto, listando requisitos de hardware e software, explica\u00e7\u00e3o completa dos recursos do produto e como us\u00e1-los em toda a sua extens\u00e3o.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do projeto<\/a> – registra os principais detalhes do projeto e produz os documentos necess\u00e1rios para implementar um projeto com sucesso. Ele pode incluir propostas de projeto<\/a>, documentos de requisitos de neg\u00f3cios<\/a>, casos de neg\u00f3cios, planos de projeto e relat\u00f3rios de status do projeto.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/p>\r\n
8 etapas para criar uma incr\u00edvel documenta\u00e7\u00e3o t\u00e9cnica<\/h2>\r\n
Aqui est\u00e3o as etapas que voc\u00ea precisa percorrer para criar uma documenta\u00e7\u00e3o t\u00e9cnica que seja bem sucedida e \u00fatil para seus usu\u00e1rios.<\/p>\r\n
Decida o tipo de p\u00fablico e o tipo de documenta\u00e7\u00e3o<\/h3>\r\n
Antes de mais nada, voc\u00ea precisa conhecer o p\u00fablico-alvo da sua documenta\u00e7\u00e3o. S\u00e3o os seus clientes, outros desenvolvedores, a equipe de produtos ou qualquer outra parte interessada? Ao saber quem \u00e9 o seu p\u00fablico, voc\u00ea poder\u00e1 adaptar o tom e o estilo da sua documenta\u00e7\u00e3o para torn\u00e1-la mais relevante e envolvente.
\r\nSe voc\u00ea n\u00e3o souber quem \u00e9 o seu p\u00fablico, sua documenta\u00e7\u00e3o n\u00e3o ter\u00e1 foco e n\u00e3o ser\u00e1 \u00fatil. Definir o p\u00fablico-alvo no est\u00e1gio inicial do processo de documenta\u00e7\u00e3o ajudar\u00e1 na cria\u00e7\u00e3o do documento e garantir\u00e1 que voc\u00ea tenha um alvo claramente definido.<\/p>\r\n
Pesquisa de t\u00f3picos<\/strong><\/h3>\r\nDepois de definir o p\u00fablico-alvo, voc\u00ea precisa pesquisar os t\u00f3picos que abordar\u00e1 em sua documenta\u00e7\u00e3o. Voc\u00ea n\u00e3o pode esperar escrever um conte\u00fado t\u00e9cnico eficaz se n\u00e3o tiver uma ideia clara dos t\u00f3picos sobre os quais escrever\u00e1. Nesse est\u00e1gio, \u00e9 uma boa ideia trabalhar com a sua equipe para fazer um brainstorming de diferentes t\u00f3picos e atribuir v\u00e1rias tarefas de pesquisa a diferentes membros da equipe.<\/p>\r\n
\u00c9 importante fazer perguntas a si mesmo:<\/p>\r\n
\r\n\t- Quais \u00e1reas queremos que nossa documenta\u00e7\u00e3o t\u00e9cnica inclua?<\/li>\r\n\t
- Qual \u00e9 o objetivo que queremos alcan\u00e7ar com nossa documenta\u00e7\u00e3o t\u00e9cnica?<\/li>\r\n\t
- J\u00e1 temos alguma documenta\u00e7\u00e3o existente com a qual podemos trabalhar?<\/li>\r\n<\/ul>\r\n
Certifique-se de que se trata de um esfor\u00e7o em equipe para pesquisar os t\u00f3picos \u2013 voc\u00ea n\u00e3o precisa ir sozinho.<\/p>\r\n
Capturar conhecimento<\/strong><\/h3>\r\nAo escrever sua documenta\u00e7\u00e3o, \u00e9 prov\u00e1vel que voc\u00ea n\u00e3o seja o \u00fanico autor. Ser\u00e1 necess\u00e1rio colaborar com outras partes interessadas da sua equipe para produzir a documenta\u00e7\u00e3o t\u00e9cnica. Nesse est\u00e1gio, voc\u00ea precisa trabalhar com especialistas no assunto para obter o conhecimento que ser\u00e1 usado para escrever os artigos.<\/p>\r\n
Reserve um tempo para descobrir quem \u00e9 a pessoa mais adequada para escrever diferentes t\u00f3picos de sua documenta\u00e7\u00e3o t\u00e9cnica e entre em contato com ela para atribuir-lhe a tarefa. Voc\u00ea tamb\u00e9m pode realizar entrevistas com seus especialistas e escrever o conte\u00fado voc\u00ea mesmo.<\/p>\r\n
Mantenha registros detalhados dos t\u00f3picos e da pessoa respons\u00e1vel por fornecer o conte\u00fado e acompanhe o est\u00e1gio em que o conte\u00fado se encontra.<\/p>\r\n
Projete modelos e organize o conte\u00fado<\/strong><\/h3>\r\nEmbora a parte mais importante da sua documenta\u00e7\u00e3o seja o conte\u00fado escrito, tamb\u00e9m \u00e9 uma boa ideia considerar a apar\u00eancia visual dos documentos para o usu\u00e1rio final. O objetivo \u00e9 ter um site de documenta\u00e7\u00e3o bem organizado e visualmente atraente, em vez de um amontoado de anota\u00e7\u00f5es mal projetadas que n\u00e3o ajudam ningu\u00e9m.<\/p>\r\n
Ao pensar no design da documenta\u00e7\u00e3o, considere a estrutura e a navega\u00e7\u00e3o do seu conte\u00fado. Seus usu\u00e1rios geralmente recorrem \u00e0 documenta\u00e7\u00e3o t\u00e9cnica para encontrar informa\u00e7\u00f5es espec\u00edficas ou uma solu\u00e7\u00e3o para um problema, portanto, sua pesquisa deve permitir que eles realizem essa tarefa rapidamente.<\/p>\r\n
Lembre-se de colocar suas informa\u00e7\u00f5es em categorias e subcategorias que os usu\u00e1rios possam pesquisar com efici\u00eancia. O ideal \u00e9 que voc\u00ea tenha uma barra de pesquisa que os usu\u00e1rios possam usar para acessar instantaneamente as informa\u00e7\u00f5es que est\u00e3o procurando.<\/p>\r\n
Comece com a cria\u00e7\u00e3o de conte\u00fado<\/strong><\/h3>\r\nVoc\u00ea j\u00e1 deve ter dado o pontap\u00e9 inicial no processo de reda\u00e7\u00e3o com a pesquisa de documenta\u00e7\u00e3o e a colabora\u00e7\u00e3o com os especialistas. Escrever documenta\u00e7\u00e3o t\u00e9cnica \u00e9 um trabalho de equipe e voc\u00ea ter\u00e1 muitos colaboradores participando desse processo colaborativo.<\/p>\r\n
Se ainda n\u00e3o o fez, re\u00fana-se com a equipe e delegue as tarefas de conte\u00fado ao membro mais adequado com base em suas habilidades. A melhor documenta\u00e7\u00e3o \u00e9 produzida quando os redatores come\u00e7am com esbo\u00e7os e direcionam sua documenta\u00e7\u00e3o para um usu\u00e1rio espec\u00edfico.<\/p>\r\n
Sua documenta\u00e7\u00e3o deve come\u00e7ar com um esbo\u00e7o de alto n\u00edvel<\/a> para cada um dos t\u00f3picos que planeja abordar. Re\u00fana o restante do conte\u00fado necess\u00e1rio para sua pe\u00e7a de conte\u00fado, juntamente com todos os recursos visuais de apoio.<\/p>\r\nLembre-se de escrever em linguagem simples e clara que seja facilmente compreens\u00edvel para o usu\u00e1rio. N\u00e3o presuma que os leitores t\u00eam o mesmo n\u00edvel de conhecimento pr\u00e9vio que voc\u00ea – inclua o m\u00e1ximo de contexto poss\u00edvel para ajudar na compreens\u00e3o. Escreva a quantidade de conte\u00fado necess\u00e1ria para transmitir seu ponto de vista e nem uma palavra a mais – menos \u00e9 definitivamente melhor quando se trata de documenta\u00e7\u00e3o.<\/p>\r\n
Revise e colabore com a sua equipe<\/strong><\/h3>\r\nDepois de come\u00e7ar a trabalhar no conte\u00fado, voc\u00ea precisar\u00e1 chamar especialistas para revisar a precis\u00e3o do conte\u00fado. Chame-os logo ap\u00f3s o primeiro rascunho e ap\u00f3s o rascunho final para dar feedback sobre sua documenta\u00e7\u00e3o. Ap\u00f3s o primeiro rascunho, voc\u00ea deve receber feedback sobre o esbo\u00e7o geral e o fluxo do documento, em vez de feedback sobre erros de digita\u00e7\u00e3o e gram\u00e1tica. Somente ap\u00f3s a revis\u00e3o final \u00e9 que voc\u00ea deseja receber cr\u00edticas detalhadas sobre a forma como redigiu o conte\u00fado.<\/p>\r\n
Procure revis\u00f5es por pares com outros membros da sua equipe que possam testar a usabilidade da sua documenta\u00e7\u00e3o t\u00e9cnica. Pe\u00e7a a outra pessoa que examine a documenta\u00e7\u00e3o e registre as \u00e1reas em que ela se perdeu ou ficou confusa. Depois de receber o feedback da revis\u00e3o por pares, incorpore as altera\u00e7\u00f5es em sua documenta\u00e7\u00e3o.<\/p>\r\n
Al\u00e9m disso, confira o nosso artigo sobre Como testar a usabilidade dos documentos t\u00e9cnicos<\/em><\/strong><\/p>\r\nPublicar o conte\u00fado<\/strong><\/h3>\r\nAp\u00f3s ter analisado seu conte\u00fado v\u00e1rias vezes, \u00e9 hora de publicar sua documenta\u00e7\u00e3o pronta para seu p\u00fablico. Quando a sua documenta\u00e7\u00e3o estiver ativa v\u00e1 para verificar se h\u00e1 atualiza\u00e7\u00f5es de \u00faltima hora e certifique-se de que isso \u00e9 livre de erros.<\/p>\r\n
Ao publicar seu conte\u00fado, talvez voc\u00ea queira usar um software de base de conhecimento como o Document360, que \u00e9 uma boa maneira de hospedar sua documenta\u00e7\u00e3o. Ele vem com arquitetura de informa\u00e7\u00f5es e organiza\u00e7\u00e3o de categorias incorporadas, al\u00e9m de uma barra de pesquisa proeminente e capacidade de resposta m\u00f3vel.<\/p>\r\n
\r\n\r\nUm software intuitivo de base de conhecimento para adicionar facilmente seu conte\u00fado e integr\u00e1-lo a qualquer aplicativo. Tente com o Document360<\/p>\r\nComece Agora<\/a><\/div>\r\n<\/div>\r\n<\/div>\r\nDepois que o site estiver no ar, talvez voc\u00ea queira realizar mais testes sobre a efic\u00e1cia da documenta\u00e7\u00e3o, coletando feedback dos usu\u00e1rios. Fa\u00e7a uma auditoria da navega\u00e7\u00e3o da sua documenta\u00e7\u00e3o para verificar se os usu\u00e1rios podem navegar facilmente e encontrar o que est\u00e3o procurando – identifique coisas como links quebrados e se os elementos de navega\u00e7\u00e3o est\u00e3o funcionando corretamente.<\/p>\r\n
Atualizar e gerenciar a documenta\u00e7\u00e3o baseada no analytics<\/strong><\/h3>\r\nSua documenta\u00e7\u00e3o t\u00e9cnica nunca est\u00e1 pronta. Se voc\u00ea estiver usando o software apropriado, voc\u00ea ter\u00e1 an\u00e1lises que podem ser revisadas que mostram a efic\u00e1cia do seu conte\u00fado. Voc\u00ea deveria estar sempre revisando sua documenta\u00e7\u00e3o para atualiza\u00e7\u00f5es e evitar deix\u00e1-la ficar parada.<\/p>\r\n
Voc\u00ea precisa manter sua documenta\u00e7\u00e3o alinhada com as novas atualiza\u00e7\u00f5es e vers\u00f5es de produtos Agende uma manuten\u00e7\u00e3o regular para seu conte\u00fado com base em dicas que voc\u00ea colhe das suas an\u00e1lises, como pesquisas falhadas ou classifica\u00e7\u00f5es negativas de artigos.<\/p>\r\n
Se voc\u00ea usar o software correto, pode salvar vers\u00f5es anteriores da sua documenta\u00e7\u00e3o, caso precise revert\u00ea-lo mais tarde.<\/p>\r\n
O que fazer e o que n\u00e3o fazer na documenta\u00e7\u00e3o t\u00e9cnica<\/strong><\/h2>\r\nFazer<\/strong><\/h3>\r\n\r\n\t- Mantenha a simplicidade e a clareza – n\u00e3o complique demais a documenta\u00e7\u00e3o nem use linguagem complexa.<\/li>\r\n\t
- Tenha sempre o usu\u00e1rio em mente – sempre que escrever uma documenta\u00e7\u00e3o, certifique-se de que est\u00e1 claro para quem ela se destina.<\/li>\r\n\t
- Torne-a visual – se puder representar o que est\u00e1 tentando transmitir com uma imagem, fa\u00e7a isso.<\/li>\r\n\t
- Passe por um processo de revis\u00e3o completo – se poss\u00edvel, certifique-se de que v\u00e1rias pessoas revisem seu trabalho durante a fase de reda\u00e7\u00e3o.<\/li>\r\n<\/ul>\r\n
N\u00e3o fazer:<\/strong><\/h3>\r\n\r\n\t- Supor que o p\u00fablico esteja familiarizado com o assunto – sempre forne\u00e7a o m\u00e1ximo de contexto poss\u00edvel.<\/li>\r\n\t
- Usar uma voz passiva – sempre use a voz ativa: \u201cEle apertou o bot\u00e3o\u201d em vez de \u2018o bot\u00e3o foi apertado por ele\u2019.<\/li>\r\n\t
- Usar acr\u00f4nimos – se precisar usar acr\u00f4nimos, indique claramente o significado do acr\u00f4nimo ao lado dele.<\/li>\r\n\t
- Tentar ser engra\u00e7ado – o que pode ser divertido para voc\u00ea pode ser insultante ou ofensivo para seus leitores.<\/li>\r\n<\/ul>\r\n
Tamb\u00e9m Leia:<\/strong> Como escrever documenta\u00e7\u00e3o inclusiva?<\/p>\r\nPensamentos finais<\/strong><\/h2>\r\nN\u00e3o cometa o erro de subestimar a import\u00e2ncia da documenta\u00e7\u00e3o t\u00e9cnica para o sucesso geral de sua empresa. Ela \u00e9 uma parte essencial da comunica\u00e7\u00e3o e significa que os membros da sua equipe n\u00e3o precisam estar literalmente dispon\u00edveis toda vez que algu\u00e9m tiver uma d\u00favida, seja um cliente ou uma parte interessada da sua equipe.<\/p>\r\n
N\u00e3o \u00e9 necess\u00e1rio abordar a documenta\u00e7\u00e3o t\u00e9cnica com pesar – se voc\u00ea seguir as etapas que descrevemos neste guia, estar\u00e1 no caminho certo para criar conte\u00fado \u00fatil para seus usu\u00e1rios. Eles ter\u00e3o a capacidade de usar seu produto e se divertir\u00e3o mais com ele, o que \u00e9 exatamente o objetivo da documenta\u00e7\u00e3o t\u00e9cnica.<\/p>\r\n
\r\n\r\nInteressado na base de conhecimento do Document360? Agende uma demonstra\u00e7\u00e3o com um de nossos especialistas.<\/p>\r\nReserve uma demonstra\u00e7\u00e3o<\/a><\/div>\r\n<\/div>\r\n<\/div>\r\n\r\n\r\n\r\nPerguntas Frequentes<\/h2>\r\n\r\n\t- \r\n
Como a documenta\u00e7\u00e3o t\u00e9cnica \u00e9 diferente da documenta\u00e7\u00e3o do usu\u00e1rio? <\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o t\u00e9cnica \u00e9 a documenta\u00e7\u00e3o que descreve como um produto ou servi\u00e7o funciona. Ela \u00e9 mais voltada para o desenvolvedor e criada para descrever (em linguagem t\u00e9cnica) o uso, a funcionalidade ou a arquitetura de um produto, sistema ou servi\u00e7o. A documenta\u00e7\u00e3o de um produto ou servi\u00e7o entregue aos usu\u00e1rios finais \u00e9 chamada de documenta\u00e7\u00e3o do usu\u00e1rio. A documenta\u00e7\u00e3o do usu\u00e1rio tem o objetivo de ajudar os usu\u00e1rios finais a entender e usar o produto ou servi\u00e7o.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t
- \r\n
Diferen\u00e7a entre documenta\u00e7\u00e3o de processos e produtos?<\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o pode ser de dois tipos: produtos e processos. A documenta\u00e7\u00e3o do produto define o produto em desenvolvimento e fornece instru\u00e7\u00f5es sobre como us\u00e1-lo. A documenta\u00e7\u00e3o do processo, por outro lado, refere-se a todo o conte\u00fado produzido durante o processo de desenvolvimento.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t
- \r\n
O que \u00e9 documenta\u00e7\u00e3o t\u00e9cnica de software? <\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o t\u00e9cnica do software define as v\u00e1rias rotas e pontos de extremidade da API que o desenvolvedor pode acessar ou pode explicar as bibliotecas, as integra\u00e7\u00f5es e as depend\u00eancias do SDK. Todos os engenheiros que j\u00e1 escreveram c\u00f3digos em qualquer linguagem, em algum momento, fizeram refer\u00eancia \u00e0 documenta\u00e7\u00e3o t\u00e9cnica.<\/p>\r\n<\/div>\r\n<\/li>\r\n<\/ul>\r\n<\/div>\r\n
Quando voc\u00ea tem uma documenta\u00e7\u00e3o t\u00e9cnica abrangente, os clientes podem consultar os documentos quando tiverem problemas t\u00e9cnicos. Isso reduz o n\u00famero de chamadas recebidas na sua fila de suporte t\u00e9cnico e significa que voc\u00ea pode dar suporte a mais clientes com um or\u00e7amento menor. A maioria dos clientes prefere solucionar os problemas por conta pr\u00f3pria em vez de ficar esperando que uma pessoa os ajude.<\/p>\r\n
Registra ideias de desenvolvedores<\/strong><\/h3>\r\nA documenta\u00e7\u00e3o do seu software pode registrar as ideias que os desenvolvedores t\u00eam em rela\u00e7\u00e3o ao seu produto de software. Mesmo que voc\u00ea n\u00e3o as implemente imediatamente, mais adiante voc\u00ea poder\u00e1 procurar recursos que talvez queira considerar ou outras altera\u00e7\u00f5es que queira fazer. Os desenvolvedores n\u00e3o necessariamente se lembram de suas ideias mais tarde, portanto, sua documenta\u00e7\u00e3o \u00e9 um bom lugar para manter um registro.<\/p>\r\n
Fornece um roteiro para projetos futuros<\/strong><\/h3>\r\nSua documenta\u00e7\u00e3o t\u00e9cnica \u00e9 um roteiro para os projetos que voc\u00ea deseja desenvolver no futuro, registrando os planos que voc\u00ea tem para o desenvolvimento do seu produto e os novos recursos que est\u00e3o sendo preparados. Ela garante que todos na sua equipe estejam na mesma p\u00e1gina e trabalhando para atingir um \u00fanico objetivo.<\/p>\r\n
Melhora a comunica\u00e7\u00e3o com interessados e desenvolvedores<\/strong><\/h3>\r\nA documenta\u00e7\u00e3o \u00e9 uma forma importante de comunica\u00e7\u00e3o – as partes interessadas e os desenvolvedores n\u00e3o precisam conversar diretamente entre si para acessar informa\u00e7\u00f5es sobre o software. A documenta\u00e7\u00e3o salva o conhecimento para a posteridade e permite que a equipe analise o trabalho que foi conclu\u00eddo anteriormente para informar as decis\u00f5es futuras.<\/p>\r\n
Tipos de documenta\u00e7\u00e3o t\u00e9cnica com exemplos<\/strong><\/h2>\r\nExistem muitos tipos diferentes de documenta\u00e7\u00e3o t\u00e9cnica \u2013 passaremos por eles agora.<\/p>\r\n
Documenta\u00e7\u00e3o t\u00e9cnica no SDLC<\/strong><\/h3>\r\nEsta \u00e9 a documenta\u00e7\u00e3o de software nos bastidores destinada aos seus desenvolvedores e outros membros da equipe.<\/p>\r\n
Documenta\u00e7\u00e3o do administrador do sistema<\/strong> – melhora \u00e9 v\u00e1lida a seguran\u00e7a, documentando os detalhes e procedimentos da configura\u00e7\u00e3o que sustentam uma pol\u00edtica de seguran\u00e7a. Eles cobrem instala\u00e7\u00f5es e atualiza\u00e7\u00f5es que auxiliam um administrador do sistema com a manuten\u00e7\u00e3o de produtos.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o de exig\u00eancia de produto<\/strong> \u2013 fornece um \u00fanico ponto de refer\u00eancia para os requisitos de entrada de design t\u00e9cnico de um produto e explica como o produto deve funcionar para atender \u00e0s necessidades dos clientes.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o de design de experi\u00eancia do usu\u00e1rio<\/strong> – um documento de trabalho de um produto desde sua concep\u00e7\u00e3o at\u00e9 a vers\u00e3o atual, e eles incluem modelos de conte\u00fado, mapas de empatia, mapas de experi\u00eancia, modelos mentais e pessoas.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do c\u00f3digo-fonte<\/strong> \u2013 documenta\u00e7\u00e3o do software que garante que seu c\u00f3digo seja leg\u00edvel, possa ser compreendido rapidamente e seja f\u00e1cil de manter pelos desenvolvedores. Inclui coment\u00e1rios de c\u00f3digo que podem explicar partes de c\u00f3digo que n\u00e3o s\u00e3o \u00f3bvias.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o da API<\/strong> <\/a>\u2013 permite que desenvolvedores trabalhem com a sua API e mostra se o seu software vai ou n\u00e3o resolver o problema deles.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do guia de manuten\u00e7\u00e3o<\/strong> \u2013 diga ao usu\u00e1rio como manter o sistema de forma eficaz e pode incluir uma defini\u00e7\u00e3o do ambiente de suporte ao software. fun\u00e7\u00f5es e responsabilidades do pessoal de manuten\u00e7\u00e3o.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do produto<\/h3>\r\n
Base de conhecimento de produtos<\/strong> \u2013 uma biblioteca de informa\u00e7\u00f5es sobre o produto do seu software que cont\u00e9m respostas para clientes procurando resolver problemas sozinhos.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nManual do usu\u00e1rio<\/strong><\/a> – cont\u00e9m extensas informa\u00e7\u00f5es sobre como instalar e operar o produto, listando requisitos de hardware e software, explica\u00e7\u00e3o completa dos recursos do produto e como us\u00e1-los em toda a sua extens\u00e3o.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do projeto<\/a> – registra os principais detalhes do projeto e produz os documentos necess\u00e1rios para implementar um projeto com sucesso. Ele pode incluir propostas de projeto<\/a>, documentos de requisitos de neg\u00f3cios<\/a>, casos de neg\u00f3cios, planos de projeto e relat\u00f3rios de status do projeto.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/p>\r\n
8 etapas para criar uma incr\u00edvel documenta\u00e7\u00e3o t\u00e9cnica<\/h2>\r\n
Aqui est\u00e3o as etapas que voc\u00ea precisa percorrer para criar uma documenta\u00e7\u00e3o t\u00e9cnica que seja bem sucedida e \u00fatil para seus usu\u00e1rios.<\/p>\r\n
Decida o tipo de p\u00fablico e o tipo de documenta\u00e7\u00e3o<\/h3>\r\n
Antes de mais nada, voc\u00ea precisa conhecer o p\u00fablico-alvo da sua documenta\u00e7\u00e3o. S\u00e3o os seus clientes, outros desenvolvedores, a equipe de produtos ou qualquer outra parte interessada? Ao saber quem \u00e9 o seu p\u00fablico, voc\u00ea poder\u00e1 adaptar o tom e o estilo da sua documenta\u00e7\u00e3o para torn\u00e1-la mais relevante e envolvente.
\r\nSe voc\u00ea n\u00e3o souber quem \u00e9 o seu p\u00fablico, sua documenta\u00e7\u00e3o n\u00e3o ter\u00e1 foco e n\u00e3o ser\u00e1 \u00fatil. Definir o p\u00fablico-alvo no est\u00e1gio inicial do processo de documenta\u00e7\u00e3o ajudar\u00e1 na cria\u00e7\u00e3o do documento e garantir\u00e1 que voc\u00ea tenha um alvo claramente definido.<\/p>\r\n
Pesquisa de t\u00f3picos<\/strong><\/h3>\r\nDepois de definir o p\u00fablico-alvo, voc\u00ea precisa pesquisar os t\u00f3picos que abordar\u00e1 em sua documenta\u00e7\u00e3o. Voc\u00ea n\u00e3o pode esperar escrever um conte\u00fado t\u00e9cnico eficaz se n\u00e3o tiver uma ideia clara dos t\u00f3picos sobre os quais escrever\u00e1. Nesse est\u00e1gio, \u00e9 uma boa ideia trabalhar com a sua equipe para fazer um brainstorming de diferentes t\u00f3picos e atribuir v\u00e1rias tarefas de pesquisa a diferentes membros da equipe.<\/p>\r\n
\u00c9 importante fazer perguntas a si mesmo:<\/p>\r\n
\r\n\t- Quais \u00e1reas queremos que nossa documenta\u00e7\u00e3o t\u00e9cnica inclua?<\/li>\r\n\t
- Qual \u00e9 o objetivo que queremos alcan\u00e7ar com nossa documenta\u00e7\u00e3o t\u00e9cnica?<\/li>\r\n\t
- J\u00e1 temos alguma documenta\u00e7\u00e3o existente com a qual podemos trabalhar?<\/li>\r\n<\/ul>\r\n
Certifique-se de que se trata de um esfor\u00e7o em equipe para pesquisar os t\u00f3picos \u2013 voc\u00ea n\u00e3o precisa ir sozinho.<\/p>\r\n
Capturar conhecimento<\/strong><\/h3>\r\nAo escrever sua documenta\u00e7\u00e3o, \u00e9 prov\u00e1vel que voc\u00ea n\u00e3o seja o \u00fanico autor. Ser\u00e1 necess\u00e1rio colaborar com outras partes interessadas da sua equipe para produzir a documenta\u00e7\u00e3o t\u00e9cnica. Nesse est\u00e1gio, voc\u00ea precisa trabalhar com especialistas no assunto para obter o conhecimento que ser\u00e1 usado para escrever os artigos.<\/p>\r\n
Reserve um tempo para descobrir quem \u00e9 a pessoa mais adequada para escrever diferentes t\u00f3picos de sua documenta\u00e7\u00e3o t\u00e9cnica e entre em contato com ela para atribuir-lhe a tarefa. Voc\u00ea tamb\u00e9m pode realizar entrevistas com seus especialistas e escrever o conte\u00fado voc\u00ea mesmo.<\/p>\r\n
Mantenha registros detalhados dos t\u00f3picos e da pessoa respons\u00e1vel por fornecer o conte\u00fado e acompanhe o est\u00e1gio em que o conte\u00fado se encontra.<\/p>\r\n
Projete modelos e organize o conte\u00fado<\/strong><\/h3>\r\nEmbora a parte mais importante da sua documenta\u00e7\u00e3o seja o conte\u00fado escrito, tamb\u00e9m \u00e9 uma boa ideia considerar a apar\u00eancia visual dos documentos para o usu\u00e1rio final. O objetivo \u00e9 ter um site de documenta\u00e7\u00e3o bem organizado e visualmente atraente, em vez de um amontoado de anota\u00e7\u00f5es mal projetadas que n\u00e3o ajudam ningu\u00e9m.<\/p>\r\n
Ao pensar no design da documenta\u00e7\u00e3o, considere a estrutura e a navega\u00e7\u00e3o do seu conte\u00fado. Seus usu\u00e1rios geralmente recorrem \u00e0 documenta\u00e7\u00e3o t\u00e9cnica para encontrar informa\u00e7\u00f5es espec\u00edficas ou uma solu\u00e7\u00e3o para um problema, portanto, sua pesquisa deve permitir que eles realizem essa tarefa rapidamente.<\/p>\r\n
Lembre-se de colocar suas informa\u00e7\u00f5es em categorias e subcategorias que os usu\u00e1rios possam pesquisar com efici\u00eancia. O ideal \u00e9 que voc\u00ea tenha uma barra de pesquisa que os usu\u00e1rios possam usar para acessar instantaneamente as informa\u00e7\u00f5es que est\u00e3o procurando.<\/p>\r\n
Comece com a cria\u00e7\u00e3o de conte\u00fado<\/strong><\/h3>\r\nVoc\u00ea j\u00e1 deve ter dado o pontap\u00e9 inicial no processo de reda\u00e7\u00e3o com a pesquisa de documenta\u00e7\u00e3o e a colabora\u00e7\u00e3o com os especialistas. Escrever documenta\u00e7\u00e3o t\u00e9cnica \u00e9 um trabalho de equipe e voc\u00ea ter\u00e1 muitos colaboradores participando desse processo colaborativo.<\/p>\r\n
Se ainda n\u00e3o o fez, re\u00fana-se com a equipe e delegue as tarefas de conte\u00fado ao membro mais adequado com base em suas habilidades. A melhor documenta\u00e7\u00e3o \u00e9 produzida quando os redatores come\u00e7am com esbo\u00e7os e direcionam sua documenta\u00e7\u00e3o para um usu\u00e1rio espec\u00edfico.<\/p>\r\n
Sua documenta\u00e7\u00e3o deve come\u00e7ar com um esbo\u00e7o de alto n\u00edvel<\/a> para cada um dos t\u00f3picos que planeja abordar. Re\u00fana o restante do conte\u00fado necess\u00e1rio para sua pe\u00e7a de conte\u00fado, juntamente com todos os recursos visuais de apoio.<\/p>\r\nLembre-se de escrever em linguagem simples e clara que seja facilmente compreens\u00edvel para o usu\u00e1rio. N\u00e3o presuma que os leitores t\u00eam o mesmo n\u00edvel de conhecimento pr\u00e9vio que voc\u00ea – inclua o m\u00e1ximo de contexto poss\u00edvel para ajudar na compreens\u00e3o. Escreva a quantidade de conte\u00fado necess\u00e1ria para transmitir seu ponto de vista e nem uma palavra a mais – menos \u00e9 definitivamente melhor quando se trata de documenta\u00e7\u00e3o.<\/p>\r\n
Revise e colabore com a sua equipe<\/strong><\/h3>\r\nDepois de come\u00e7ar a trabalhar no conte\u00fado, voc\u00ea precisar\u00e1 chamar especialistas para revisar a precis\u00e3o do conte\u00fado. Chame-os logo ap\u00f3s o primeiro rascunho e ap\u00f3s o rascunho final para dar feedback sobre sua documenta\u00e7\u00e3o. Ap\u00f3s o primeiro rascunho, voc\u00ea deve receber feedback sobre o esbo\u00e7o geral e o fluxo do documento, em vez de feedback sobre erros de digita\u00e7\u00e3o e gram\u00e1tica. Somente ap\u00f3s a revis\u00e3o final \u00e9 que voc\u00ea deseja receber cr\u00edticas detalhadas sobre a forma como redigiu o conte\u00fado.<\/p>\r\n
Procure revis\u00f5es por pares com outros membros da sua equipe que possam testar a usabilidade da sua documenta\u00e7\u00e3o t\u00e9cnica. Pe\u00e7a a outra pessoa que examine a documenta\u00e7\u00e3o e registre as \u00e1reas em que ela se perdeu ou ficou confusa. Depois de receber o feedback da revis\u00e3o por pares, incorpore as altera\u00e7\u00f5es em sua documenta\u00e7\u00e3o.<\/p>\r\n
Al\u00e9m disso, confira o nosso artigo sobre Como testar a usabilidade dos documentos t\u00e9cnicos<\/em><\/strong><\/p>\r\nPublicar o conte\u00fado<\/strong><\/h3>\r\nAp\u00f3s ter analisado seu conte\u00fado v\u00e1rias vezes, \u00e9 hora de publicar sua documenta\u00e7\u00e3o pronta para seu p\u00fablico. Quando a sua documenta\u00e7\u00e3o estiver ativa v\u00e1 para verificar se h\u00e1 atualiza\u00e7\u00f5es de \u00faltima hora e certifique-se de que isso \u00e9 livre de erros.<\/p>\r\n
Ao publicar seu conte\u00fado, talvez voc\u00ea queira usar um software de base de conhecimento como o Document360, que \u00e9 uma boa maneira de hospedar sua documenta\u00e7\u00e3o. Ele vem com arquitetura de informa\u00e7\u00f5es e organiza\u00e7\u00e3o de categorias incorporadas, al\u00e9m de uma barra de pesquisa proeminente e capacidade de resposta m\u00f3vel.<\/p>\r\n
\r\n\r\nUm software intuitivo de base de conhecimento para adicionar facilmente seu conte\u00fado e integr\u00e1-lo a qualquer aplicativo. Tente com o Document360<\/p>\r\nComece Agora<\/a><\/div>\r\n<\/div>\r\n<\/div>\r\nDepois que o site estiver no ar, talvez voc\u00ea queira realizar mais testes sobre a efic\u00e1cia da documenta\u00e7\u00e3o, coletando feedback dos usu\u00e1rios. Fa\u00e7a uma auditoria da navega\u00e7\u00e3o da sua documenta\u00e7\u00e3o para verificar se os usu\u00e1rios podem navegar facilmente e encontrar o que est\u00e3o procurando – identifique coisas como links quebrados e se os elementos de navega\u00e7\u00e3o est\u00e3o funcionando corretamente.<\/p>\r\n
Atualizar e gerenciar a documenta\u00e7\u00e3o baseada no analytics<\/strong><\/h3>\r\nSua documenta\u00e7\u00e3o t\u00e9cnica nunca est\u00e1 pronta. Se voc\u00ea estiver usando o software apropriado, voc\u00ea ter\u00e1 an\u00e1lises que podem ser revisadas que mostram a efic\u00e1cia do seu conte\u00fado. Voc\u00ea deveria estar sempre revisando sua documenta\u00e7\u00e3o para atualiza\u00e7\u00f5es e evitar deix\u00e1-la ficar parada.<\/p>\r\n
Voc\u00ea precisa manter sua documenta\u00e7\u00e3o alinhada com as novas atualiza\u00e7\u00f5es e vers\u00f5es de produtos Agende uma manuten\u00e7\u00e3o regular para seu conte\u00fado com base em dicas que voc\u00ea colhe das suas an\u00e1lises, como pesquisas falhadas ou classifica\u00e7\u00f5es negativas de artigos.<\/p>\r\n
Se voc\u00ea usar o software correto, pode salvar vers\u00f5es anteriores da sua documenta\u00e7\u00e3o, caso precise revert\u00ea-lo mais tarde.<\/p>\r\n
O que fazer e o que n\u00e3o fazer na documenta\u00e7\u00e3o t\u00e9cnica<\/strong><\/h2>\r\nFazer<\/strong><\/h3>\r\n\r\n\t- Mantenha a simplicidade e a clareza – n\u00e3o complique demais a documenta\u00e7\u00e3o nem use linguagem complexa.<\/li>\r\n\t
- Tenha sempre o usu\u00e1rio em mente – sempre que escrever uma documenta\u00e7\u00e3o, certifique-se de que est\u00e1 claro para quem ela se destina.<\/li>\r\n\t
- Torne-a visual – se puder representar o que est\u00e1 tentando transmitir com uma imagem, fa\u00e7a isso.<\/li>\r\n\t
- Passe por um processo de revis\u00e3o completo – se poss\u00edvel, certifique-se de que v\u00e1rias pessoas revisem seu trabalho durante a fase de reda\u00e7\u00e3o.<\/li>\r\n<\/ul>\r\n
N\u00e3o fazer:<\/strong><\/h3>\r\n\r\n\t- Supor que o p\u00fablico esteja familiarizado com o assunto – sempre forne\u00e7a o m\u00e1ximo de contexto poss\u00edvel.<\/li>\r\n\t
- Usar uma voz passiva – sempre use a voz ativa: \u201cEle apertou o bot\u00e3o\u201d em vez de \u2018o bot\u00e3o foi apertado por ele\u2019.<\/li>\r\n\t
- Usar acr\u00f4nimos – se precisar usar acr\u00f4nimos, indique claramente o significado do acr\u00f4nimo ao lado dele.<\/li>\r\n\t
- Tentar ser engra\u00e7ado – o que pode ser divertido para voc\u00ea pode ser insultante ou ofensivo para seus leitores.<\/li>\r\n<\/ul>\r\n
Tamb\u00e9m Leia:<\/strong> Como escrever documenta\u00e7\u00e3o inclusiva?<\/p>\r\nPensamentos finais<\/strong><\/h2>\r\nN\u00e3o cometa o erro de subestimar a import\u00e2ncia da documenta\u00e7\u00e3o t\u00e9cnica para o sucesso geral de sua empresa. Ela \u00e9 uma parte essencial da comunica\u00e7\u00e3o e significa que os membros da sua equipe n\u00e3o precisam estar literalmente dispon\u00edveis toda vez que algu\u00e9m tiver uma d\u00favida, seja um cliente ou uma parte interessada da sua equipe.<\/p>\r\n
N\u00e3o \u00e9 necess\u00e1rio abordar a documenta\u00e7\u00e3o t\u00e9cnica com pesar – se voc\u00ea seguir as etapas que descrevemos neste guia, estar\u00e1 no caminho certo para criar conte\u00fado \u00fatil para seus usu\u00e1rios. Eles ter\u00e3o a capacidade de usar seu produto e se divertir\u00e3o mais com ele, o que \u00e9 exatamente o objetivo da documenta\u00e7\u00e3o t\u00e9cnica.<\/p>\r\n
\r\n\r\nInteressado na base de conhecimento do Document360? Agende uma demonstra\u00e7\u00e3o com um de nossos especialistas.<\/p>\r\nReserve uma demonstra\u00e7\u00e3o<\/a><\/div>\r\n<\/div>\r\n<\/div>\r\n\r\n\r\n\r\nPerguntas Frequentes<\/h2>\r\n\r\n\t- \r\n
Como a documenta\u00e7\u00e3o t\u00e9cnica \u00e9 diferente da documenta\u00e7\u00e3o do usu\u00e1rio? <\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o t\u00e9cnica \u00e9 a documenta\u00e7\u00e3o que descreve como um produto ou servi\u00e7o funciona. Ela \u00e9 mais voltada para o desenvolvedor e criada para descrever (em linguagem t\u00e9cnica) o uso, a funcionalidade ou a arquitetura de um produto, sistema ou servi\u00e7o. A documenta\u00e7\u00e3o de um produto ou servi\u00e7o entregue aos usu\u00e1rios finais \u00e9 chamada de documenta\u00e7\u00e3o do usu\u00e1rio. A documenta\u00e7\u00e3o do usu\u00e1rio tem o objetivo de ajudar os usu\u00e1rios finais a entender e usar o produto ou servi\u00e7o.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t
- \r\n
Diferen\u00e7a entre documenta\u00e7\u00e3o de processos e produtos?<\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o pode ser de dois tipos: produtos e processos. A documenta\u00e7\u00e3o do produto define o produto em desenvolvimento e fornece instru\u00e7\u00f5es sobre como us\u00e1-lo. A documenta\u00e7\u00e3o do processo, por outro lado, refere-se a todo o conte\u00fado produzido durante o processo de desenvolvimento.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t
- \r\n
O que \u00e9 documenta\u00e7\u00e3o t\u00e9cnica de software? <\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o t\u00e9cnica do software define as v\u00e1rias rotas e pontos de extremidade da API que o desenvolvedor pode acessar ou pode explicar as bibliotecas, as integra\u00e7\u00f5es e as depend\u00eancias do SDK. Todos os engenheiros que j\u00e1 escreveram c\u00f3digos em qualquer linguagem, em algum momento, fizeram refer\u00eancia \u00e0 documenta\u00e7\u00e3o t\u00e9cnica.<\/p>\r\n<\/div>\r\n<\/li>\r\n<\/ul>\r\n<\/div>\r\n
Sua documenta\u00e7\u00e3o t\u00e9cnica \u00e9 um roteiro para os projetos que voc\u00ea deseja desenvolver no futuro, registrando os planos que voc\u00ea tem para o desenvolvimento do seu produto e os novos recursos que est\u00e3o sendo preparados. Ela garante que todos na sua equipe estejam na mesma p\u00e1gina e trabalhando para atingir um \u00fanico objetivo.<\/p>\r\n
Melhora a comunica\u00e7\u00e3o com interessados e desenvolvedores<\/strong><\/h3>\r\nA documenta\u00e7\u00e3o \u00e9 uma forma importante de comunica\u00e7\u00e3o – as partes interessadas e os desenvolvedores n\u00e3o precisam conversar diretamente entre si para acessar informa\u00e7\u00f5es sobre o software. A documenta\u00e7\u00e3o salva o conhecimento para a posteridade e permite que a equipe analise o trabalho que foi conclu\u00eddo anteriormente para informar as decis\u00f5es futuras.<\/p>\r\n
Tipos de documenta\u00e7\u00e3o t\u00e9cnica com exemplos<\/strong><\/h2>\r\nExistem muitos tipos diferentes de documenta\u00e7\u00e3o t\u00e9cnica \u2013 passaremos por eles agora.<\/p>\r\n
Documenta\u00e7\u00e3o t\u00e9cnica no SDLC<\/strong><\/h3>\r\nEsta \u00e9 a documenta\u00e7\u00e3o de software nos bastidores destinada aos seus desenvolvedores e outros membros da equipe.<\/p>\r\n
Documenta\u00e7\u00e3o do administrador do sistema<\/strong> – melhora \u00e9 v\u00e1lida a seguran\u00e7a, documentando os detalhes e procedimentos da configura\u00e7\u00e3o que sustentam uma pol\u00edtica de seguran\u00e7a. Eles cobrem instala\u00e7\u00f5es e atualiza\u00e7\u00f5es que auxiliam um administrador do sistema com a manuten\u00e7\u00e3o de produtos.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o de exig\u00eancia de produto<\/strong> \u2013 fornece um \u00fanico ponto de refer\u00eancia para os requisitos de entrada de design t\u00e9cnico de um produto e explica como o produto deve funcionar para atender \u00e0s necessidades dos clientes.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o de design de experi\u00eancia do usu\u00e1rio<\/strong> – um documento de trabalho de um produto desde sua concep\u00e7\u00e3o at\u00e9 a vers\u00e3o atual, e eles incluem modelos de conte\u00fado, mapas de empatia, mapas de experi\u00eancia, modelos mentais e pessoas.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do c\u00f3digo-fonte<\/strong> \u2013 documenta\u00e7\u00e3o do software que garante que seu c\u00f3digo seja leg\u00edvel, possa ser compreendido rapidamente e seja f\u00e1cil de manter pelos desenvolvedores. Inclui coment\u00e1rios de c\u00f3digo que podem explicar partes de c\u00f3digo que n\u00e3o s\u00e3o \u00f3bvias.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o da API<\/strong> <\/a>\u2013 permite que desenvolvedores trabalhem com a sua API e mostra se o seu software vai ou n\u00e3o resolver o problema deles.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do guia de manuten\u00e7\u00e3o<\/strong> \u2013 diga ao usu\u00e1rio como manter o sistema de forma eficaz e pode incluir uma defini\u00e7\u00e3o do ambiente de suporte ao software. fun\u00e7\u00f5es e responsabilidades do pessoal de manuten\u00e7\u00e3o.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do produto<\/h3>\r\n
Base de conhecimento de produtos<\/strong> \u2013 uma biblioteca de informa\u00e7\u00f5es sobre o produto do seu software que cont\u00e9m respostas para clientes procurando resolver problemas sozinhos.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nManual do usu\u00e1rio<\/strong><\/a> – cont\u00e9m extensas informa\u00e7\u00f5es sobre como instalar e operar o produto, listando requisitos de hardware e software, explica\u00e7\u00e3o completa dos recursos do produto e como us\u00e1-los em toda a sua extens\u00e3o.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do projeto<\/a> – registra os principais detalhes do projeto e produz os documentos necess\u00e1rios para implementar um projeto com sucesso. Ele pode incluir propostas de projeto<\/a>, documentos de requisitos de neg\u00f3cios<\/a>, casos de neg\u00f3cios, planos de projeto e relat\u00f3rios de status do projeto.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/p>\r\n
8 etapas para criar uma incr\u00edvel documenta\u00e7\u00e3o t\u00e9cnica<\/h2>\r\n
Aqui est\u00e3o as etapas que voc\u00ea precisa percorrer para criar uma documenta\u00e7\u00e3o t\u00e9cnica que seja bem sucedida e \u00fatil para seus usu\u00e1rios.<\/p>\r\n
Decida o tipo de p\u00fablico e o tipo de documenta\u00e7\u00e3o<\/h3>\r\n
Antes de mais nada, voc\u00ea precisa conhecer o p\u00fablico-alvo da sua documenta\u00e7\u00e3o. S\u00e3o os seus clientes, outros desenvolvedores, a equipe de produtos ou qualquer outra parte interessada? Ao saber quem \u00e9 o seu p\u00fablico, voc\u00ea poder\u00e1 adaptar o tom e o estilo da sua documenta\u00e7\u00e3o para torn\u00e1-la mais relevante e envolvente.
\r\nSe voc\u00ea n\u00e3o souber quem \u00e9 o seu p\u00fablico, sua documenta\u00e7\u00e3o n\u00e3o ter\u00e1 foco e n\u00e3o ser\u00e1 \u00fatil. Definir o p\u00fablico-alvo no est\u00e1gio inicial do processo de documenta\u00e7\u00e3o ajudar\u00e1 na cria\u00e7\u00e3o do documento e garantir\u00e1 que voc\u00ea tenha um alvo claramente definido.<\/p>\r\n
Pesquisa de t\u00f3picos<\/strong><\/h3>\r\nDepois de definir o p\u00fablico-alvo, voc\u00ea precisa pesquisar os t\u00f3picos que abordar\u00e1 em sua documenta\u00e7\u00e3o. Voc\u00ea n\u00e3o pode esperar escrever um conte\u00fado t\u00e9cnico eficaz se n\u00e3o tiver uma ideia clara dos t\u00f3picos sobre os quais escrever\u00e1. Nesse est\u00e1gio, \u00e9 uma boa ideia trabalhar com a sua equipe para fazer um brainstorming de diferentes t\u00f3picos e atribuir v\u00e1rias tarefas de pesquisa a diferentes membros da equipe.<\/p>\r\n
\u00c9 importante fazer perguntas a si mesmo:<\/p>\r\n
\r\n\t- Quais \u00e1reas queremos que nossa documenta\u00e7\u00e3o t\u00e9cnica inclua?<\/li>\r\n\t
- Qual \u00e9 o objetivo que queremos alcan\u00e7ar com nossa documenta\u00e7\u00e3o t\u00e9cnica?<\/li>\r\n\t
- J\u00e1 temos alguma documenta\u00e7\u00e3o existente com a qual podemos trabalhar?<\/li>\r\n<\/ul>\r\n
Certifique-se de que se trata de um esfor\u00e7o em equipe para pesquisar os t\u00f3picos \u2013 voc\u00ea n\u00e3o precisa ir sozinho.<\/p>\r\n
Capturar conhecimento<\/strong><\/h3>\r\nAo escrever sua documenta\u00e7\u00e3o, \u00e9 prov\u00e1vel que voc\u00ea n\u00e3o seja o \u00fanico autor. Ser\u00e1 necess\u00e1rio colaborar com outras partes interessadas da sua equipe para produzir a documenta\u00e7\u00e3o t\u00e9cnica. Nesse est\u00e1gio, voc\u00ea precisa trabalhar com especialistas no assunto para obter o conhecimento que ser\u00e1 usado para escrever os artigos.<\/p>\r\n
Reserve um tempo para descobrir quem \u00e9 a pessoa mais adequada para escrever diferentes t\u00f3picos de sua documenta\u00e7\u00e3o t\u00e9cnica e entre em contato com ela para atribuir-lhe a tarefa. Voc\u00ea tamb\u00e9m pode realizar entrevistas com seus especialistas e escrever o conte\u00fado voc\u00ea mesmo.<\/p>\r\n
Mantenha registros detalhados dos t\u00f3picos e da pessoa respons\u00e1vel por fornecer o conte\u00fado e acompanhe o est\u00e1gio em que o conte\u00fado se encontra.<\/p>\r\n
Projete modelos e organize o conte\u00fado<\/strong><\/h3>\r\nEmbora a parte mais importante da sua documenta\u00e7\u00e3o seja o conte\u00fado escrito, tamb\u00e9m \u00e9 uma boa ideia considerar a apar\u00eancia visual dos documentos para o usu\u00e1rio final. O objetivo \u00e9 ter um site de documenta\u00e7\u00e3o bem organizado e visualmente atraente, em vez de um amontoado de anota\u00e7\u00f5es mal projetadas que n\u00e3o ajudam ningu\u00e9m.<\/p>\r\n
Ao pensar no design da documenta\u00e7\u00e3o, considere a estrutura e a navega\u00e7\u00e3o do seu conte\u00fado. Seus usu\u00e1rios geralmente recorrem \u00e0 documenta\u00e7\u00e3o t\u00e9cnica para encontrar informa\u00e7\u00f5es espec\u00edficas ou uma solu\u00e7\u00e3o para um problema, portanto, sua pesquisa deve permitir que eles realizem essa tarefa rapidamente.<\/p>\r\n
Lembre-se de colocar suas informa\u00e7\u00f5es em categorias e subcategorias que os usu\u00e1rios possam pesquisar com efici\u00eancia. O ideal \u00e9 que voc\u00ea tenha uma barra de pesquisa que os usu\u00e1rios possam usar para acessar instantaneamente as informa\u00e7\u00f5es que est\u00e3o procurando.<\/p>\r\n
Comece com a cria\u00e7\u00e3o de conte\u00fado<\/strong><\/h3>\r\nVoc\u00ea j\u00e1 deve ter dado o pontap\u00e9 inicial no processo de reda\u00e7\u00e3o com a pesquisa de documenta\u00e7\u00e3o e a colabora\u00e7\u00e3o com os especialistas. Escrever documenta\u00e7\u00e3o t\u00e9cnica \u00e9 um trabalho de equipe e voc\u00ea ter\u00e1 muitos colaboradores participando desse processo colaborativo.<\/p>\r\n
Se ainda n\u00e3o o fez, re\u00fana-se com a equipe e delegue as tarefas de conte\u00fado ao membro mais adequado com base em suas habilidades. A melhor documenta\u00e7\u00e3o \u00e9 produzida quando os redatores come\u00e7am com esbo\u00e7os e direcionam sua documenta\u00e7\u00e3o para um usu\u00e1rio espec\u00edfico.<\/p>\r\n
Sua documenta\u00e7\u00e3o deve come\u00e7ar com um esbo\u00e7o de alto n\u00edvel<\/a> para cada um dos t\u00f3picos que planeja abordar. Re\u00fana o restante do conte\u00fado necess\u00e1rio para sua pe\u00e7a de conte\u00fado, juntamente com todos os recursos visuais de apoio.<\/p>\r\nLembre-se de escrever em linguagem simples e clara que seja facilmente compreens\u00edvel para o usu\u00e1rio. N\u00e3o presuma que os leitores t\u00eam o mesmo n\u00edvel de conhecimento pr\u00e9vio que voc\u00ea – inclua o m\u00e1ximo de contexto poss\u00edvel para ajudar na compreens\u00e3o. Escreva a quantidade de conte\u00fado necess\u00e1ria para transmitir seu ponto de vista e nem uma palavra a mais – menos \u00e9 definitivamente melhor quando se trata de documenta\u00e7\u00e3o.<\/p>\r\n
Revise e colabore com a sua equipe<\/strong><\/h3>\r\nDepois de come\u00e7ar a trabalhar no conte\u00fado, voc\u00ea precisar\u00e1 chamar especialistas para revisar a precis\u00e3o do conte\u00fado. Chame-os logo ap\u00f3s o primeiro rascunho e ap\u00f3s o rascunho final para dar feedback sobre sua documenta\u00e7\u00e3o. Ap\u00f3s o primeiro rascunho, voc\u00ea deve receber feedback sobre o esbo\u00e7o geral e o fluxo do documento, em vez de feedback sobre erros de digita\u00e7\u00e3o e gram\u00e1tica. Somente ap\u00f3s a revis\u00e3o final \u00e9 que voc\u00ea deseja receber cr\u00edticas detalhadas sobre a forma como redigiu o conte\u00fado.<\/p>\r\n
Procure revis\u00f5es por pares com outros membros da sua equipe que possam testar a usabilidade da sua documenta\u00e7\u00e3o t\u00e9cnica. Pe\u00e7a a outra pessoa que examine a documenta\u00e7\u00e3o e registre as \u00e1reas em que ela se perdeu ou ficou confusa. Depois de receber o feedback da revis\u00e3o por pares, incorpore as altera\u00e7\u00f5es em sua documenta\u00e7\u00e3o.<\/p>\r\n
Al\u00e9m disso, confira o nosso artigo sobre Como testar a usabilidade dos documentos t\u00e9cnicos<\/em><\/strong><\/p>\r\nPublicar o conte\u00fado<\/strong><\/h3>\r\nAp\u00f3s ter analisado seu conte\u00fado v\u00e1rias vezes, \u00e9 hora de publicar sua documenta\u00e7\u00e3o pronta para seu p\u00fablico. Quando a sua documenta\u00e7\u00e3o estiver ativa v\u00e1 para verificar se h\u00e1 atualiza\u00e7\u00f5es de \u00faltima hora e certifique-se de que isso \u00e9 livre de erros.<\/p>\r\n
Ao publicar seu conte\u00fado, talvez voc\u00ea queira usar um software de base de conhecimento como o Document360, que \u00e9 uma boa maneira de hospedar sua documenta\u00e7\u00e3o. Ele vem com arquitetura de informa\u00e7\u00f5es e organiza\u00e7\u00e3o de categorias incorporadas, al\u00e9m de uma barra de pesquisa proeminente e capacidade de resposta m\u00f3vel.<\/p>\r\n
\r\n\r\nUm software intuitivo de base de conhecimento para adicionar facilmente seu conte\u00fado e integr\u00e1-lo a qualquer aplicativo. Tente com o Document360<\/p>\r\nComece Agora<\/a><\/div>\r\n<\/div>\r\n<\/div>\r\nDepois que o site estiver no ar, talvez voc\u00ea queira realizar mais testes sobre a efic\u00e1cia da documenta\u00e7\u00e3o, coletando feedback dos usu\u00e1rios. Fa\u00e7a uma auditoria da navega\u00e7\u00e3o da sua documenta\u00e7\u00e3o para verificar se os usu\u00e1rios podem navegar facilmente e encontrar o que est\u00e3o procurando – identifique coisas como links quebrados e se os elementos de navega\u00e7\u00e3o est\u00e3o funcionando corretamente.<\/p>\r\n
Atualizar e gerenciar a documenta\u00e7\u00e3o baseada no analytics<\/strong><\/h3>\r\nSua documenta\u00e7\u00e3o t\u00e9cnica nunca est\u00e1 pronta. Se voc\u00ea estiver usando o software apropriado, voc\u00ea ter\u00e1 an\u00e1lises que podem ser revisadas que mostram a efic\u00e1cia do seu conte\u00fado. Voc\u00ea deveria estar sempre revisando sua documenta\u00e7\u00e3o para atualiza\u00e7\u00f5es e evitar deix\u00e1-la ficar parada.<\/p>\r\n
Voc\u00ea precisa manter sua documenta\u00e7\u00e3o alinhada com as novas atualiza\u00e7\u00f5es e vers\u00f5es de produtos Agende uma manuten\u00e7\u00e3o regular para seu conte\u00fado com base em dicas que voc\u00ea colhe das suas an\u00e1lises, como pesquisas falhadas ou classifica\u00e7\u00f5es negativas de artigos.<\/p>\r\n
Se voc\u00ea usar o software correto, pode salvar vers\u00f5es anteriores da sua documenta\u00e7\u00e3o, caso precise revert\u00ea-lo mais tarde.<\/p>\r\n
O que fazer e o que n\u00e3o fazer na documenta\u00e7\u00e3o t\u00e9cnica<\/strong><\/h2>\r\nFazer<\/strong><\/h3>\r\n\r\n\t- Mantenha a simplicidade e a clareza – n\u00e3o complique demais a documenta\u00e7\u00e3o nem use linguagem complexa.<\/li>\r\n\t
- Tenha sempre o usu\u00e1rio em mente – sempre que escrever uma documenta\u00e7\u00e3o, certifique-se de que est\u00e1 claro para quem ela se destina.<\/li>\r\n\t
- Torne-a visual – se puder representar o que est\u00e1 tentando transmitir com uma imagem, fa\u00e7a isso.<\/li>\r\n\t
- Passe por um processo de revis\u00e3o completo – se poss\u00edvel, certifique-se de que v\u00e1rias pessoas revisem seu trabalho durante a fase de reda\u00e7\u00e3o.<\/li>\r\n<\/ul>\r\n
N\u00e3o fazer:<\/strong><\/h3>\r\n\r\n\t- Supor que o p\u00fablico esteja familiarizado com o assunto – sempre forne\u00e7a o m\u00e1ximo de contexto poss\u00edvel.<\/li>\r\n\t
- Usar uma voz passiva – sempre use a voz ativa: \u201cEle apertou o bot\u00e3o\u201d em vez de \u2018o bot\u00e3o foi apertado por ele\u2019.<\/li>\r\n\t
- Usar acr\u00f4nimos – se precisar usar acr\u00f4nimos, indique claramente o significado do acr\u00f4nimo ao lado dele.<\/li>\r\n\t
- Tentar ser engra\u00e7ado – o que pode ser divertido para voc\u00ea pode ser insultante ou ofensivo para seus leitores.<\/li>\r\n<\/ul>\r\n
Tamb\u00e9m Leia:<\/strong> Como escrever documenta\u00e7\u00e3o inclusiva?<\/p>\r\nPensamentos finais<\/strong><\/h2>\r\nN\u00e3o cometa o erro de subestimar a import\u00e2ncia da documenta\u00e7\u00e3o t\u00e9cnica para o sucesso geral de sua empresa. Ela \u00e9 uma parte essencial da comunica\u00e7\u00e3o e significa que os membros da sua equipe n\u00e3o precisam estar literalmente dispon\u00edveis toda vez que algu\u00e9m tiver uma d\u00favida, seja um cliente ou uma parte interessada da sua equipe.<\/p>\r\n
N\u00e3o \u00e9 necess\u00e1rio abordar a documenta\u00e7\u00e3o t\u00e9cnica com pesar – se voc\u00ea seguir as etapas que descrevemos neste guia, estar\u00e1 no caminho certo para criar conte\u00fado \u00fatil para seus usu\u00e1rios. Eles ter\u00e3o a capacidade de usar seu produto e se divertir\u00e3o mais com ele, o que \u00e9 exatamente o objetivo da documenta\u00e7\u00e3o t\u00e9cnica.<\/p>\r\n
\r\n\r\nInteressado na base de conhecimento do Document360? Agende uma demonstra\u00e7\u00e3o com um de nossos especialistas.<\/p>\r\nReserve uma demonstra\u00e7\u00e3o<\/a><\/div>\r\n<\/div>\r\n<\/div>\r\n\r\n\r\n\r\nPerguntas Frequentes<\/h2>\r\n\r\n\t- \r\n
Como a documenta\u00e7\u00e3o t\u00e9cnica \u00e9 diferente da documenta\u00e7\u00e3o do usu\u00e1rio? <\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o t\u00e9cnica \u00e9 a documenta\u00e7\u00e3o que descreve como um produto ou servi\u00e7o funciona. Ela \u00e9 mais voltada para o desenvolvedor e criada para descrever (em linguagem t\u00e9cnica) o uso, a funcionalidade ou a arquitetura de um produto, sistema ou servi\u00e7o. A documenta\u00e7\u00e3o de um produto ou servi\u00e7o entregue aos usu\u00e1rios finais \u00e9 chamada de documenta\u00e7\u00e3o do usu\u00e1rio. A documenta\u00e7\u00e3o do usu\u00e1rio tem o objetivo de ajudar os usu\u00e1rios finais a entender e usar o produto ou servi\u00e7o.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t
- \r\n
Diferen\u00e7a entre documenta\u00e7\u00e3o de processos e produtos?<\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o pode ser de dois tipos: produtos e processos. A documenta\u00e7\u00e3o do produto define o produto em desenvolvimento e fornece instru\u00e7\u00f5es sobre como us\u00e1-lo. A documenta\u00e7\u00e3o do processo, por outro lado, refere-se a todo o conte\u00fado produzido durante o processo de desenvolvimento.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t
- \r\n
O que \u00e9 documenta\u00e7\u00e3o t\u00e9cnica de software? <\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o t\u00e9cnica do software define as v\u00e1rias rotas e pontos de extremidade da API que o desenvolvedor pode acessar ou pode explicar as bibliotecas, as integra\u00e7\u00f5es e as depend\u00eancias do SDK. Todos os engenheiros que j\u00e1 escreveram c\u00f3digos em qualquer linguagem, em algum momento, fizeram refer\u00eancia \u00e0 documenta\u00e7\u00e3o t\u00e9cnica.<\/p>\r\n<\/div>\r\n<\/li>\r\n<\/ul>\r\n<\/div>\r\n
Existem muitos tipos diferentes de documenta\u00e7\u00e3o t\u00e9cnica \u2013 passaremos por eles agora.<\/p>\r\n
Documenta\u00e7\u00e3o t\u00e9cnica no SDLC<\/strong><\/h3>\r\nEsta \u00e9 a documenta\u00e7\u00e3o de software nos bastidores destinada aos seus desenvolvedores e outros membros da equipe.<\/p>\r\n
Documenta\u00e7\u00e3o do administrador do sistema<\/strong> – melhora \u00e9 v\u00e1lida a seguran\u00e7a, documentando os detalhes e procedimentos da configura\u00e7\u00e3o que sustentam uma pol\u00edtica de seguran\u00e7a. Eles cobrem instala\u00e7\u00f5es e atualiza\u00e7\u00f5es que auxiliam um administrador do sistema com a manuten\u00e7\u00e3o de produtos.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o de exig\u00eancia de produto<\/strong> \u2013 fornece um \u00fanico ponto de refer\u00eancia para os requisitos de entrada de design t\u00e9cnico de um produto e explica como o produto deve funcionar para atender \u00e0s necessidades dos clientes.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o de design de experi\u00eancia do usu\u00e1rio<\/strong> – um documento de trabalho de um produto desde sua concep\u00e7\u00e3o at\u00e9 a vers\u00e3o atual, e eles incluem modelos de conte\u00fado, mapas de empatia, mapas de experi\u00eancia, modelos mentais e pessoas.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do c\u00f3digo-fonte<\/strong> \u2013 documenta\u00e7\u00e3o do software que garante que seu c\u00f3digo seja leg\u00edvel, possa ser compreendido rapidamente e seja f\u00e1cil de manter pelos desenvolvedores. Inclui coment\u00e1rios de c\u00f3digo que podem explicar partes de c\u00f3digo que n\u00e3o s\u00e3o \u00f3bvias.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o da API<\/strong> <\/a>\u2013 permite que desenvolvedores trabalhem com a sua API e mostra se o seu software vai ou n\u00e3o resolver o problema deles.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do guia de manuten\u00e7\u00e3o<\/strong> \u2013 diga ao usu\u00e1rio como manter o sistema de forma eficaz e pode incluir uma defini\u00e7\u00e3o do ambiente de suporte ao software. fun\u00e7\u00f5es e responsabilidades do pessoal de manuten\u00e7\u00e3o.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do produto<\/h3>\r\n
Base de conhecimento de produtos<\/strong> \u2013 uma biblioteca de informa\u00e7\u00f5es sobre o produto do seu software que cont\u00e9m respostas para clientes procurando resolver problemas sozinhos.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nManual do usu\u00e1rio<\/strong><\/a> – cont\u00e9m extensas informa\u00e7\u00f5es sobre como instalar e operar o produto, listando requisitos de hardware e software, explica\u00e7\u00e3o completa dos recursos do produto e como us\u00e1-los em toda a sua extens\u00e3o.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\nDocumenta\u00e7\u00e3o do projeto<\/a> – registra os principais detalhes do projeto e produz os documentos necess\u00e1rios para implementar um projeto com sucesso. Ele pode incluir propostas de projeto<\/a>, documentos de requisitos de neg\u00f3cios<\/a>, casos de neg\u00f3cios, planos de projeto e relat\u00f3rios de status do projeto.<\/p>\r\n<\/p>\r\n
Fonte da imagem<\/p>\r\n
8 etapas para criar uma incr\u00edvel documenta\u00e7\u00e3o t\u00e9cnica<\/h2>\r\n
Aqui est\u00e3o as etapas que voc\u00ea precisa percorrer para criar uma documenta\u00e7\u00e3o t\u00e9cnica que seja bem sucedida e \u00fatil para seus usu\u00e1rios.<\/p>\r\n
Decida o tipo de p\u00fablico e o tipo de documenta\u00e7\u00e3o<\/h3>\r\n
Antes de mais nada, voc\u00ea precisa conhecer o p\u00fablico-alvo da sua documenta\u00e7\u00e3o. S\u00e3o os seus clientes, outros desenvolvedores, a equipe de produtos ou qualquer outra parte interessada? Ao saber quem \u00e9 o seu p\u00fablico, voc\u00ea poder\u00e1 adaptar o tom e o estilo da sua documenta\u00e7\u00e3o para torn\u00e1-la mais relevante e envolvente.
\r\nSe voc\u00ea n\u00e3o souber quem \u00e9 o seu p\u00fablico, sua documenta\u00e7\u00e3o n\u00e3o ter\u00e1 foco e n\u00e3o ser\u00e1 \u00fatil. Definir o p\u00fablico-alvo no est\u00e1gio inicial do processo de documenta\u00e7\u00e3o ajudar\u00e1 na cria\u00e7\u00e3o do documento e garantir\u00e1 que voc\u00ea tenha um alvo claramente definido.<\/p>\r\n
Pesquisa de t\u00f3picos<\/strong><\/h3>\r\nDepois de definir o p\u00fablico-alvo, voc\u00ea precisa pesquisar os t\u00f3picos que abordar\u00e1 em sua documenta\u00e7\u00e3o. Voc\u00ea n\u00e3o pode esperar escrever um conte\u00fado t\u00e9cnico eficaz se n\u00e3o tiver uma ideia clara dos t\u00f3picos sobre os quais escrever\u00e1. Nesse est\u00e1gio, \u00e9 uma boa ideia trabalhar com a sua equipe para fazer um brainstorming de diferentes t\u00f3picos e atribuir v\u00e1rias tarefas de pesquisa a diferentes membros da equipe.<\/p>\r\n
\u00c9 importante fazer perguntas a si mesmo:<\/p>\r\n
\r\n\t- Quais \u00e1reas queremos que nossa documenta\u00e7\u00e3o t\u00e9cnica inclua?<\/li>\r\n\t
- Qual \u00e9 o objetivo que queremos alcan\u00e7ar com nossa documenta\u00e7\u00e3o t\u00e9cnica?<\/li>\r\n\t
- J\u00e1 temos alguma documenta\u00e7\u00e3o existente com a qual podemos trabalhar?<\/li>\r\n<\/ul>\r\n
Certifique-se de que se trata de um esfor\u00e7o em equipe para pesquisar os t\u00f3picos \u2013 voc\u00ea n\u00e3o precisa ir sozinho.<\/p>\r\n
Capturar conhecimento<\/strong><\/h3>\r\nAo escrever sua documenta\u00e7\u00e3o, \u00e9 prov\u00e1vel que voc\u00ea n\u00e3o seja o \u00fanico autor. Ser\u00e1 necess\u00e1rio colaborar com outras partes interessadas da sua equipe para produzir a documenta\u00e7\u00e3o t\u00e9cnica. Nesse est\u00e1gio, voc\u00ea precisa trabalhar com especialistas no assunto para obter o conhecimento que ser\u00e1 usado para escrever os artigos.<\/p>\r\n
Reserve um tempo para descobrir quem \u00e9 a pessoa mais adequada para escrever diferentes t\u00f3picos de sua documenta\u00e7\u00e3o t\u00e9cnica e entre em contato com ela para atribuir-lhe a tarefa. Voc\u00ea tamb\u00e9m pode realizar entrevistas com seus especialistas e escrever o conte\u00fado voc\u00ea mesmo.<\/p>\r\n
Mantenha registros detalhados dos t\u00f3picos e da pessoa respons\u00e1vel por fornecer o conte\u00fado e acompanhe o est\u00e1gio em que o conte\u00fado se encontra.<\/p>\r\n
Projete modelos e organize o conte\u00fado<\/strong><\/h3>\r\nEmbora a parte mais importante da sua documenta\u00e7\u00e3o seja o conte\u00fado escrito, tamb\u00e9m \u00e9 uma boa ideia considerar a apar\u00eancia visual dos documentos para o usu\u00e1rio final. O objetivo \u00e9 ter um site de documenta\u00e7\u00e3o bem organizado e visualmente atraente, em vez de um amontoado de anota\u00e7\u00f5es mal projetadas que n\u00e3o ajudam ningu\u00e9m.<\/p>\r\n
Ao pensar no design da documenta\u00e7\u00e3o, considere a estrutura e a navega\u00e7\u00e3o do seu conte\u00fado. Seus usu\u00e1rios geralmente recorrem \u00e0 documenta\u00e7\u00e3o t\u00e9cnica para encontrar informa\u00e7\u00f5es espec\u00edficas ou uma solu\u00e7\u00e3o para um problema, portanto, sua pesquisa deve permitir que eles realizem essa tarefa rapidamente.<\/p>\r\n
Lembre-se de colocar suas informa\u00e7\u00f5es em categorias e subcategorias que os usu\u00e1rios possam pesquisar com efici\u00eancia. O ideal \u00e9 que voc\u00ea tenha uma barra de pesquisa que os usu\u00e1rios possam usar para acessar instantaneamente as informa\u00e7\u00f5es que est\u00e3o procurando.<\/p>\r\n
Comece com a cria\u00e7\u00e3o de conte\u00fado<\/strong><\/h3>\r\nVoc\u00ea j\u00e1 deve ter dado o pontap\u00e9 inicial no processo de reda\u00e7\u00e3o com a pesquisa de documenta\u00e7\u00e3o e a colabora\u00e7\u00e3o com os especialistas. Escrever documenta\u00e7\u00e3o t\u00e9cnica \u00e9 um trabalho de equipe e voc\u00ea ter\u00e1 muitos colaboradores participando desse processo colaborativo.<\/p>\r\n
Se ainda n\u00e3o o fez, re\u00fana-se com a equipe e delegue as tarefas de conte\u00fado ao membro mais adequado com base em suas habilidades. A melhor documenta\u00e7\u00e3o \u00e9 produzida quando os redatores come\u00e7am com esbo\u00e7os e direcionam sua documenta\u00e7\u00e3o para um usu\u00e1rio espec\u00edfico.<\/p>\r\n
Sua documenta\u00e7\u00e3o deve come\u00e7ar com um esbo\u00e7o de alto n\u00edvel<\/a> para cada um dos t\u00f3picos que planeja abordar. Re\u00fana o restante do conte\u00fado necess\u00e1rio para sua pe\u00e7a de conte\u00fado, juntamente com todos os recursos visuais de apoio.<\/p>\r\nLembre-se de escrever em linguagem simples e clara que seja facilmente compreens\u00edvel para o usu\u00e1rio. N\u00e3o presuma que os leitores t\u00eam o mesmo n\u00edvel de conhecimento pr\u00e9vio que voc\u00ea – inclua o m\u00e1ximo de contexto poss\u00edvel para ajudar na compreens\u00e3o. Escreva a quantidade de conte\u00fado necess\u00e1ria para transmitir seu ponto de vista e nem uma palavra a mais – menos \u00e9 definitivamente melhor quando se trata de documenta\u00e7\u00e3o.<\/p>\r\n
Revise e colabore com a sua equipe<\/strong><\/h3>\r\nDepois de come\u00e7ar a trabalhar no conte\u00fado, voc\u00ea precisar\u00e1 chamar especialistas para revisar a precis\u00e3o do conte\u00fado. Chame-os logo ap\u00f3s o primeiro rascunho e ap\u00f3s o rascunho final para dar feedback sobre sua documenta\u00e7\u00e3o. Ap\u00f3s o primeiro rascunho, voc\u00ea deve receber feedback sobre o esbo\u00e7o geral e o fluxo do documento, em vez de feedback sobre erros de digita\u00e7\u00e3o e gram\u00e1tica. Somente ap\u00f3s a revis\u00e3o final \u00e9 que voc\u00ea deseja receber cr\u00edticas detalhadas sobre a forma como redigiu o conte\u00fado.<\/p>\r\n
Procure revis\u00f5es por pares com outros membros da sua equipe que possam testar a usabilidade da sua documenta\u00e7\u00e3o t\u00e9cnica. Pe\u00e7a a outra pessoa que examine a documenta\u00e7\u00e3o e registre as \u00e1reas em que ela se perdeu ou ficou confusa. Depois de receber o feedback da revis\u00e3o por pares, incorpore as altera\u00e7\u00f5es em sua documenta\u00e7\u00e3o.<\/p>\r\n
Al\u00e9m disso, confira o nosso artigo sobre Como testar a usabilidade dos documentos t\u00e9cnicos<\/em><\/strong><\/p>\r\nPublicar o conte\u00fado<\/strong><\/h3>\r\nAp\u00f3s ter analisado seu conte\u00fado v\u00e1rias vezes, \u00e9 hora de publicar sua documenta\u00e7\u00e3o pronta para seu p\u00fablico. Quando a sua documenta\u00e7\u00e3o estiver ativa v\u00e1 para verificar se h\u00e1 atualiza\u00e7\u00f5es de \u00faltima hora e certifique-se de que isso \u00e9 livre de erros.<\/p>\r\n
Ao publicar seu conte\u00fado, talvez voc\u00ea queira usar um software de base de conhecimento como o Document360, que \u00e9 uma boa maneira de hospedar sua documenta\u00e7\u00e3o. Ele vem com arquitetura de informa\u00e7\u00f5es e organiza\u00e7\u00e3o de categorias incorporadas, al\u00e9m de uma barra de pesquisa proeminente e capacidade de resposta m\u00f3vel.<\/p>\r\n
\r\n\r\nUm software intuitivo de base de conhecimento para adicionar facilmente seu conte\u00fado e integr\u00e1-lo a qualquer aplicativo. Tente com o Document360<\/p>\r\nComece Agora<\/a><\/div>\r\n<\/div>\r\n<\/div>\r\nDepois que o site estiver no ar, talvez voc\u00ea queira realizar mais testes sobre a efic\u00e1cia da documenta\u00e7\u00e3o, coletando feedback dos usu\u00e1rios. Fa\u00e7a uma auditoria da navega\u00e7\u00e3o da sua documenta\u00e7\u00e3o para verificar se os usu\u00e1rios podem navegar facilmente e encontrar o que est\u00e3o procurando – identifique coisas como links quebrados e se os elementos de navega\u00e7\u00e3o est\u00e3o funcionando corretamente.<\/p>\r\n
Atualizar e gerenciar a documenta\u00e7\u00e3o baseada no analytics<\/strong><\/h3>\r\nSua documenta\u00e7\u00e3o t\u00e9cnica nunca est\u00e1 pronta. Se voc\u00ea estiver usando o software apropriado, voc\u00ea ter\u00e1 an\u00e1lises que podem ser revisadas que mostram a efic\u00e1cia do seu conte\u00fado. Voc\u00ea deveria estar sempre revisando sua documenta\u00e7\u00e3o para atualiza\u00e7\u00f5es e evitar deix\u00e1-la ficar parada.<\/p>\r\n
Voc\u00ea precisa manter sua documenta\u00e7\u00e3o alinhada com as novas atualiza\u00e7\u00f5es e vers\u00f5es de produtos Agende uma manuten\u00e7\u00e3o regular para seu conte\u00fado com base em dicas que voc\u00ea colhe das suas an\u00e1lises, como pesquisas falhadas ou classifica\u00e7\u00f5es negativas de artigos.<\/p>\r\n
Se voc\u00ea usar o software correto, pode salvar vers\u00f5es anteriores da sua documenta\u00e7\u00e3o, caso precise revert\u00ea-lo mais tarde.<\/p>\r\n
O que fazer e o que n\u00e3o fazer na documenta\u00e7\u00e3o t\u00e9cnica<\/strong><\/h2>\r\nFazer<\/strong><\/h3>\r\n\r\n\t- Mantenha a simplicidade e a clareza – n\u00e3o complique demais a documenta\u00e7\u00e3o nem use linguagem complexa.<\/li>\r\n\t
- Tenha sempre o usu\u00e1rio em mente – sempre que escrever uma documenta\u00e7\u00e3o, certifique-se de que est\u00e1 claro para quem ela se destina.<\/li>\r\n\t
- Torne-a visual – se puder representar o que est\u00e1 tentando transmitir com uma imagem, fa\u00e7a isso.<\/li>\r\n\t
- Passe por um processo de revis\u00e3o completo – se poss\u00edvel, certifique-se de que v\u00e1rias pessoas revisem seu trabalho durante a fase de reda\u00e7\u00e3o.<\/li>\r\n<\/ul>\r\n
N\u00e3o fazer:<\/strong><\/h3>\r\n\r\n\t- Supor que o p\u00fablico esteja familiarizado com o assunto – sempre forne\u00e7a o m\u00e1ximo de contexto poss\u00edvel.<\/li>\r\n\t
- Usar uma voz passiva – sempre use a voz ativa: \u201cEle apertou o bot\u00e3o\u201d em vez de \u2018o bot\u00e3o foi apertado por ele\u2019.<\/li>\r\n\t
- Usar acr\u00f4nimos – se precisar usar acr\u00f4nimos, indique claramente o significado do acr\u00f4nimo ao lado dele.<\/li>\r\n\t
- Tentar ser engra\u00e7ado – o que pode ser divertido para voc\u00ea pode ser insultante ou ofensivo para seus leitores.<\/li>\r\n<\/ul>\r\n
Tamb\u00e9m Leia:<\/strong> Como escrever documenta\u00e7\u00e3o inclusiva?<\/p>\r\nPensamentos finais<\/strong><\/h2>\r\nN\u00e3o cometa o erro de subestimar a import\u00e2ncia da documenta\u00e7\u00e3o t\u00e9cnica para o sucesso geral de sua empresa. Ela \u00e9 uma parte essencial da comunica\u00e7\u00e3o e significa que os membros da sua equipe n\u00e3o precisam estar literalmente dispon\u00edveis toda vez que algu\u00e9m tiver uma d\u00favida, seja um cliente ou uma parte interessada da sua equipe.<\/p>\r\n
N\u00e3o \u00e9 necess\u00e1rio abordar a documenta\u00e7\u00e3o t\u00e9cnica com pesar – se voc\u00ea seguir as etapas que descrevemos neste guia, estar\u00e1 no caminho certo para criar conte\u00fado \u00fatil para seus usu\u00e1rios. Eles ter\u00e3o a capacidade de usar seu produto e se divertir\u00e3o mais com ele, o que \u00e9 exatamente o objetivo da documenta\u00e7\u00e3o t\u00e9cnica.<\/p>\r\n
\r\n\r\nInteressado na base de conhecimento do Document360? Agende uma demonstra\u00e7\u00e3o com um de nossos especialistas.<\/p>\r\nReserve uma demonstra\u00e7\u00e3o<\/a><\/div>\r\n<\/div>\r\n<\/div>\r\n\r\n\r\n\r\nPerguntas Frequentes<\/h2>\r\n\r\n\t- \r\n
Como a documenta\u00e7\u00e3o t\u00e9cnica \u00e9 diferente da documenta\u00e7\u00e3o do usu\u00e1rio? <\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o t\u00e9cnica \u00e9 a documenta\u00e7\u00e3o que descreve como um produto ou servi\u00e7o funciona. Ela \u00e9 mais voltada para o desenvolvedor e criada para descrever (em linguagem t\u00e9cnica) o uso, a funcionalidade ou a arquitetura de um produto, sistema ou servi\u00e7o. A documenta\u00e7\u00e3o de um produto ou servi\u00e7o entregue aos usu\u00e1rios finais \u00e9 chamada de documenta\u00e7\u00e3o do usu\u00e1rio. A documenta\u00e7\u00e3o do usu\u00e1rio tem o objetivo de ajudar os usu\u00e1rios finais a entender e usar o produto ou servi\u00e7o.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t
- \r\n
Diferen\u00e7a entre documenta\u00e7\u00e3o de processos e produtos?<\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o pode ser de dois tipos: produtos e processos. A documenta\u00e7\u00e3o do produto define o produto em desenvolvimento e fornece instru\u00e7\u00f5es sobre como us\u00e1-lo. A documenta\u00e7\u00e3o do processo, por outro lado, refere-se a todo o conte\u00fado produzido durante o processo de desenvolvimento.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t
- \r\n
O que \u00e9 documenta\u00e7\u00e3o t\u00e9cnica de software? <\/a><\/h3>\r\n\r\nA documenta\u00e7\u00e3o t\u00e9cnica do software define as v\u00e1rias rotas e pontos de extremidade da API que o desenvolvedor pode acessar ou pode explicar as bibliotecas, as integra\u00e7\u00f5es e as depend\u00eancias do SDK. Todos os engenheiros que j\u00e1 escreveram c\u00f3digos em qualquer linguagem, em algum momento, fizeram refer\u00eancia \u00e0 documenta\u00e7\u00e3o t\u00e9cnica.<\/p>\r\n<\/div>\r\n<\/li>\r\n<\/ul>\r\n<\/div>\r\n
<\/p>\r\n
Fonte da imagem<\/a><\/p>\r\n Documenta\u00e7\u00e3o de exig\u00eancia de produto<\/strong> \u2013 fornece um \u00fanico ponto de refer\u00eancia para os requisitos de entrada de design t\u00e9cnico de um produto e explica como o produto deve funcionar para atender \u00e0s necessidades dos clientes.<\/p>\r\n Fonte da imagem<\/a><\/p>\r\n Documenta\u00e7\u00e3o de design de experi\u00eancia do usu\u00e1rio<\/strong> – um documento de trabalho de um produto desde sua concep\u00e7\u00e3o at\u00e9 a vers\u00e3o atual, e eles incluem modelos de conte\u00fado, mapas de empatia, mapas de experi\u00eancia, modelos mentais e pessoas.<\/p>\r\n Fonte da imagem<\/a><\/p>\r\n Documenta\u00e7\u00e3o do c\u00f3digo-fonte<\/strong> \u2013 documenta\u00e7\u00e3o do software que garante que seu c\u00f3digo seja leg\u00edvel, possa ser compreendido rapidamente e seja f\u00e1cil de manter pelos desenvolvedores. Inclui coment\u00e1rios de c\u00f3digo que podem explicar partes de c\u00f3digo que n\u00e3o s\u00e3o \u00f3bvias.<\/p>\r\n Fonte da imagem<\/a><\/p>\r\n Documenta\u00e7\u00e3o da API<\/strong> <\/a>\u2013 permite que desenvolvedores trabalhem com a sua API e mostra se o seu software vai ou n\u00e3o resolver o problema deles.<\/p>\r\n Fonte da imagem<\/a><\/p>\r\n Documenta\u00e7\u00e3o do guia de manuten\u00e7\u00e3o<\/strong> \u2013 diga ao usu\u00e1rio como manter o sistema de forma eficaz e pode incluir uma defini\u00e7\u00e3o do ambiente de suporte ao software. fun\u00e7\u00f5es e responsabilidades do pessoal de manuten\u00e7\u00e3o.<\/p>\r\n Fonte da imagem<\/a><\/p>\r\n Base de conhecimento de produtos<\/strong> \u2013 uma biblioteca de informa\u00e7\u00f5es sobre o produto do seu software que cont\u00e9m respostas para clientes procurando resolver problemas sozinhos.<\/p>\r\n Fonte da imagem<\/a><\/p>\r\n Manual do usu\u00e1rio<\/strong><\/a> – cont\u00e9m extensas informa\u00e7\u00f5es sobre como instalar e operar o produto, listando requisitos de hardware e software, explica\u00e7\u00e3o completa dos recursos do produto e como us\u00e1-los em toda a sua extens\u00e3o.<\/p>\r\n Fonte da imagem<\/a><\/p>\r\n Documenta\u00e7\u00e3o do projeto<\/a> – registra os principais detalhes do projeto e produz os documentos necess\u00e1rios para implementar um projeto com sucesso. Ele pode incluir propostas de projeto<\/a>, documentos de requisitos de neg\u00f3cios<\/a>, casos de neg\u00f3cios, planos de projeto e relat\u00f3rios de status do projeto.<\/p>\r\n Fonte da imagem<\/p>\r\n Aqui est\u00e3o as etapas que voc\u00ea precisa percorrer para criar uma documenta\u00e7\u00e3o t\u00e9cnica que seja bem sucedida e \u00fatil para seus usu\u00e1rios.<\/p>\r\n Antes de mais nada, voc\u00ea precisa conhecer o p\u00fablico-alvo da sua documenta\u00e7\u00e3o. S\u00e3o os seus clientes, outros desenvolvedores, a equipe de produtos ou qualquer outra parte interessada? Ao saber quem \u00e9 o seu p\u00fablico, voc\u00ea poder\u00e1 adaptar o tom e o estilo da sua documenta\u00e7\u00e3o para torn\u00e1-la mais relevante e envolvente. Depois de definir o p\u00fablico-alvo, voc\u00ea precisa pesquisar os t\u00f3picos que abordar\u00e1 em sua documenta\u00e7\u00e3o. Voc\u00ea n\u00e3o pode esperar escrever um conte\u00fado t\u00e9cnico eficaz se n\u00e3o tiver uma ideia clara dos t\u00f3picos sobre os quais escrever\u00e1. Nesse est\u00e1gio, \u00e9 uma boa ideia trabalhar com a sua equipe para fazer um brainstorming de diferentes t\u00f3picos e atribuir v\u00e1rias tarefas de pesquisa a diferentes membros da equipe.<\/p>\r\n \u00c9 importante fazer perguntas a si mesmo:<\/p>\r\n Certifique-se de que se trata de um esfor\u00e7o em equipe para pesquisar os t\u00f3picos \u2013 voc\u00ea n\u00e3o precisa ir sozinho.<\/p>\r\n Ao escrever sua documenta\u00e7\u00e3o, \u00e9 prov\u00e1vel que voc\u00ea n\u00e3o seja o \u00fanico autor. Ser\u00e1 necess\u00e1rio colaborar com outras partes interessadas da sua equipe para produzir a documenta\u00e7\u00e3o t\u00e9cnica. Nesse est\u00e1gio, voc\u00ea precisa trabalhar com especialistas no assunto para obter o conhecimento que ser\u00e1 usado para escrever os artigos.<\/p>\r\n Reserve um tempo para descobrir quem \u00e9 a pessoa mais adequada para escrever diferentes t\u00f3picos de sua documenta\u00e7\u00e3o t\u00e9cnica e entre em contato com ela para atribuir-lhe a tarefa. Voc\u00ea tamb\u00e9m pode realizar entrevistas com seus especialistas e escrever o conte\u00fado voc\u00ea mesmo.<\/p>\r\n Mantenha registros detalhados dos t\u00f3picos e da pessoa respons\u00e1vel por fornecer o conte\u00fado e acompanhe o est\u00e1gio em que o conte\u00fado se encontra.<\/p>\r\n Embora a parte mais importante da sua documenta\u00e7\u00e3o seja o conte\u00fado escrito, tamb\u00e9m \u00e9 uma boa ideia considerar a apar\u00eancia visual dos documentos para o usu\u00e1rio final. O objetivo \u00e9 ter um site de documenta\u00e7\u00e3o bem organizado e visualmente atraente, em vez de um amontoado de anota\u00e7\u00f5es mal projetadas que n\u00e3o ajudam ningu\u00e9m.<\/p>\r\n Ao pensar no design da documenta\u00e7\u00e3o, considere a estrutura e a navega\u00e7\u00e3o do seu conte\u00fado. Seus usu\u00e1rios geralmente recorrem \u00e0 documenta\u00e7\u00e3o t\u00e9cnica para encontrar informa\u00e7\u00f5es espec\u00edficas ou uma solu\u00e7\u00e3o para um problema, portanto, sua pesquisa deve permitir que eles realizem essa tarefa rapidamente.<\/p>\r\n Lembre-se de colocar suas informa\u00e7\u00f5es em categorias e subcategorias que os usu\u00e1rios possam pesquisar com efici\u00eancia. O ideal \u00e9 que voc\u00ea tenha uma barra de pesquisa que os usu\u00e1rios possam usar para acessar instantaneamente as informa\u00e7\u00f5es que est\u00e3o procurando.<\/p>\r\n Voc\u00ea j\u00e1 deve ter dado o pontap\u00e9 inicial no processo de reda\u00e7\u00e3o com a pesquisa de documenta\u00e7\u00e3o e a colabora\u00e7\u00e3o com os especialistas. Escrever documenta\u00e7\u00e3o t\u00e9cnica \u00e9 um trabalho de equipe e voc\u00ea ter\u00e1 muitos colaboradores participando desse processo colaborativo.<\/p>\r\n Se ainda n\u00e3o o fez, re\u00fana-se com a equipe e delegue as tarefas de conte\u00fado ao membro mais adequado com base em suas habilidades. A melhor documenta\u00e7\u00e3o \u00e9 produzida quando os redatores come\u00e7am com esbo\u00e7os e direcionam sua documenta\u00e7\u00e3o para um usu\u00e1rio espec\u00edfico.<\/p>\r\n Sua documenta\u00e7\u00e3o deve come\u00e7ar com um esbo\u00e7o de alto n\u00edvel<\/a> para cada um dos t\u00f3picos que planeja abordar. Re\u00fana o restante do conte\u00fado necess\u00e1rio para sua pe\u00e7a de conte\u00fado, juntamente com todos os recursos visuais de apoio.<\/p>\r\n Lembre-se de escrever em linguagem simples e clara que seja facilmente compreens\u00edvel para o usu\u00e1rio. N\u00e3o presuma que os leitores t\u00eam o mesmo n\u00edvel de conhecimento pr\u00e9vio que voc\u00ea – inclua o m\u00e1ximo de contexto poss\u00edvel para ajudar na compreens\u00e3o. Escreva a quantidade de conte\u00fado necess\u00e1ria para transmitir seu ponto de vista e nem uma palavra a mais – menos \u00e9 definitivamente melhor quando se trata de documenta\u00e7\u00e3o.<\/p>\r\n Depois de come\u00e7ar a trabalhar no conte\u00fado, voc\u00ea precisar\u00e1 chamar especialistas para revisar a precis\u00e3o do conte\u00fado. Chame-os logo ap\u00f3s o primeiro rascunho e ap\u00f3s o rascunho final para dar feedback sobre sua documenta\u00e7\u00e3o. Ap\u00f3s o primeiro rascunho, voc\u00ea deve receber feedback sobre o esbo\u00e7o geral e o fluxo do documento, em vez de feedback sobre erros de digita\u00e7\u00e3o e gram\u00e1tica. Somente ap\u00f3s a revis\u00e3o final \u00e9 que voc\u00ea deseja receber cr\u00edticas detalhadas sobre a forma como redigiu o conte\u00fado.<\/p>\r\n Procure revis\u00f5es por pares com outros membros da sua equipe que possam testar a usabilidade da sua documenta\u00e7\u00e3o t\u00e9cnica. Pe\u00e7a a outra pessoa que examine a documenta\u00e7\u00e3o e registre as \u00e1reas em que ela se perdeu ou ficou confusa. Depois de receber o feedback da revis\u00e3o por pares, incorpore as altera\u00e7\u00f5es em sua documenta\u00e7\u00e3o.<\/p>\r\n Al\u00e9m disso, confira o nosso artigo sobre Como testar a usabilidade dos documentos t\u00e9cnicos<\/em><\/strong><\/p>\r\n Ap\u00f3s ter analisado seu conte\u00fado v\u00e1rias vezes, \u00e9 hora de publicar sua documenta\u00e7\u00e3o pronta para seu p\u00fablico. Quando a sua documenta\u00e7\u00e3o estiver ativa v\u00e1 para verificar se h\u00e1 atualiza\u00e7\u00f5es de \u00faltima hora e certifique-se de que isso \u00e9 livre de erros.<\/p>\r\n Ao publicar seu conte\u00fado, talvez voc\u00ea queira usar um software de base de conhecimento como o Document360, que \u00e9 uma boa maneira de hospedar sua documenta\u00e7\u00e3o. Ele vem com arquitetura de informa\u00e7\u00f5es e organiza\u00e7\u00e3o de categorias incorporadas, al\u00e9m de uma barra de pesquisa proeminente e capacidade de resposta m\u00f3vel.<\/p>\r\n Um software intuitivo de base de conhecimento para adicionar facilmente seu conte\u00fado e integr\u00e1-lo a qualquer aplicativo. Tente com o Document360<\/p>\r\nComece Agora<\/a><\/div>\r\n Depois que o site estiver no ar, talvez voc\u00ea queira realizar mais testes sobre a efic\u00e1cia da documenta\u00e7\u00e3o, coletando feedback dos usu\u00e1rios. Fa\u00e7a uma auditoria da navega\u00e7\u00e3o da sua documenta\u00e7\u00e3o para verificar se os usu\u00e1rios podem navegar facilmente e encontrar o que est\u00e3o procurando – identifique coisas como links quebrados e se os elementos de navega\u00e7\u00e3o est\u00e3o funcionando corretamente.<\/p>\r\n Sua documenta\u00e7\u00e3o t\u00e9cnica nunca est\u00e1 pronta. Se voc\u00ea estiver usando o software apropriado, voc\u00ea ter\u00e1 an\u00e1lises que podem ser revisadas que mostram a efic\u00e1cia do seu conte\u00fado. Voc\u00ea deveria estar sempre revisando sua documenta\u00e7\u00e3o para atualiza\u00e7\u00f5es e evitar deix\u00e1-la ficar parada.<\/p>\r\n Voc\u00ea precisa manter sua documenta\u00e7\u00e3o alinhada com as novas atualiza\u00e7\u00f5es e vers\u00f5es de produtos Agende uma manuten\u00e7\u00e3o regular para seu conte\u00fado com base em dicas que voc\u00ea colhe das suas an\u00e1lises, como pesquisas falhadas ou classifica\u00e7\u00f5es negativas de artigos.<\/p>\r\n Se voc\u00ea usar o software correto, pode salvar vers\u00f5es anteriores da sua documenta\u00e7\u00e3o, caso precise revert\u00ea-lo mais tarde.<\/p>\r\n Tamb\u00e9m Leia:<\/strong> Como escrever documenta\u00e7\u00e3o inclusiva?<\/p>\r\n N\u00e3o cometa o erro de subestimar a import\u00e2ncia da documenta\u00e7\u00e3o t\u00e9cnica para o sucesso geral de sua empresa. Ela \u00e9 uma parte essencial da comunica\u00e7\u00e3o e significa que os membros da sua equipe n\u00e3o precisam estar literalmente dispon\u00edveis toda vez que algu\u00e9m tiver uma d\u00favida, seja um cliente ou uma parte interessada da sua equipe.<\/p>\r\n N\u00e3o \u00e9 necess\u00e1rio abordar a documenta\u00e7\u00e3o t\u00e9cnica com pesar – se voc\u00ea seguir as etapas que descrevemos neste guia, estar\u00e1 no caminho certo para criar conte\u00fado \u00fatil para seus usu\u00e1rios. Eles ter\u00e3o a capacidade de usar seu produto e se divertir\u00e3o mais com ele, o que \u00e9 exatamente o objetivo da documenta\u00e7\u00e3o t\u00e9cnica.<\/p>\r\n Interessado na base de conhecimento do Document360? Agende uma demonstra\u00e7\u00e3o com um de nossos especialistas.<\/p>\r\nReserve uma demonstra\u00e7\u00e3o<\/a><\/div>\r\n A documenta\u00e7\u00e3o t\u00e9cnica \u00e9 a documenta\u00e7\u00e3o que descreve como um produto ou servi\u00e7o funciona. Ela \u00e9 mais voltada para o desenvolvedor e criada para descrever (em linguagem t\u00e9cnica) o uso, a funcionalidade ou a arquitetura de um produto, sistema ou servi\u00e7o. A documenta\u00e7\u00e3o de um produto ou servi\u00e7o entregue aos usu\u00e1rios finais \u00e9 chamada de documenta\u00e7\u00e3o do usu\u00e1rio. A documenta\u00e7\u00e3o do usu\u00e1rio tem o objetivo de ajudar os usu\u00e1rios finais a entender e usar o produto ou servi\u00e7o.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t A documenta\u00e7\u00e3o pode ser de dois tipos: produtos e processos. A documenta\u00e7\u00e3o do produto define o produto em desenvolvimento e fornece instru\u00e7\u00f5es sobre como us\u00e1-lo. A documenta\u00e7\u00e3o do processo, por outro lado, refere-se a todo o conte\u00fado produzido durante o processo de desenvolvimento.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t A documenta\u00e7\u00e3o t\u00e9cnica do software define as v\u00e1rias rotas e pontos de extremidade da API que o desenvolvedor pode acessar ou pode explicar as bibliotecas, as integra\u00e7\u00f5es e as depend\u00eancias do SDK. Todos os engenheiros que j\u00e1 escreveram c\u00f3digos em qualquer linguagem, em algum momento, fizeram refer\u00eancia \u00e0 documenta\u00e7\u00e3o t\u00e9cnica.<\/p>\r\n<\/div>\r\n<\/li>\r\n<\/ul>\r\n<\/div>\r\n<\/p>\r\n<\/p>\r\n<\/p>\r\n<\/p>\r\n<\/p>\r\nDocumenta\u00e7\u00e3o do produto<\/h3>\r\n
<\/p>\r\n<\/p>\r\n<\/p>\r\n8 etapas para criar uma incr\u00edvel documenta\u00e7\u00e3o t\u00e9cnica<\/h2>\r\n
Decida o tipo de p\u00fablico e o tipo de documenta\u00e7\u00e3o<\/h3>\r\n
\r\nSe voc\u00ea n\u00e3o souber quem \u00e9 o seu p\u00fablico, sua documenta\u00e7\u00e3o n\u00e3o ter\u00e1 foco e n\u00e3o ser\u00e1 \u00fatil. Definir o p\u00fablico-alvo no est\u00e1gio inicial do processo de documenta\u00e7\u00e3o ajudar\u00e1 na cria\u00e7\u00e3o do documento e garantir\u00e1 que voc\u00ea tenha um alvo claramente definido.<\/p>\r\nPesquisa de t\u00f3picos<\/strong><\/h3>\r\n
\r\n\t
Capturar conhecimento<\/strong><\/h3>\r\n
Projete modelos e organize o conte\u00fado<\/strong><\/h3>\r\n
Comece com a cria\u00e7\u00e3o de conte\u00fado<\/strong><\/h3>\r\n
Revise e colabore com a sua equipe<\/strong><\/h3>\r\n
Publicar o conte\u00fado<\/strong><\/h3>\r\n
<\/div>\r\n<\/div>\r\nAtualizar e gerenciar a documenta\u00e7\u00e3o baseada no analytics<\/strong><\/h3>\r\n
O que fazer e o que n\u00e3o fazer na documenta\u00e7\u00e3o t\u00e9cnica<\/strong><\/h2>\r\n
Fazer<\/strong><\/h3>\r\n
\r\n\t
N\u00e3o fazer:<\/strong><\/h3>\r\n
\r\n\t
Pensamentos finais<\/strong><\/h2>\r\n
<\/div>\r\n<\/div>\r\nPerguntas Frequentes<\/h2>\r\n
\r\n\t
Como a documenta\u00e7\u00e3o t\u00e9cnica \u00e9 diferente da documenta\u00e7\u00e3o do usu\u00e1rio? <\/a><\/h3>\r\n
Diferen\u00e7a entre documenta\u00e7\u00e3o de processos e produtos?<\/a><\/h3>\r\n
O que \u00e9 documenta\u00e7\u00e3o t\u00e9cnica de software? <\/a><\/h3>\r\n