Dicas sobre como criar uma boa documentação formação técnica

O usuário final é o público para o qual você está criando a documentação técnica. É fundamental entender o público adequadamente antes de começar a escrever. Considere suas necessidades, nível de habilidade e capacidade de compreender os pontos que você irá abordar. Toda a documentação técnica não cobre as informações necessárias ou é muito difícil de entender é inadequada.

Antes de começar a escrever, você deve entender o produto ou ferramenta que você vai escrever sobre. O processo de pesquisa geralmente envolve entrevistar especialistas no assunto que têm um conhecimento aprofundado sobre o produto. O especialista no assunto poderia ser um engenheiro ou programador que fez parte da equipe que desenvolveu o produto. Você também pode experimentar o produto ou software se.

É importante fazer anotações de cada pedaço de informação relevante, especialmente dados altamente técnico que pode ser difícil lembrar em uma data posterior. Organizar a informação e criar uma tabela de conteúdos. Verifique a tabela de conteúdo com um especialista no assunto e começar a trabalhar no primeiro esboço.

Como você juntar as informações, você deve seguir o guia de estilo também requerida. Use voz ativa e evitar o jargão desnecessário. documentação de formação técnica deve ser claro e direto ao ponto. Adicionar imagens, testes e dicas em intervalos regulares. Isto irá manter o leitor ocupados e também simplificar o processo de aprendizagem. Se a documentação inclui how-to procedimentos ou etapas, você deve executar os procedimentos a si mesmo e incluir capturas de tela ou imagens sempre que necessário. procedimentos de atualização a cada vez que o software ou produtos alterações.

Em uma base regular, se reunir com o especialista no assunto e seu editor (se tiver). Tê-los rever o conteúdo ou capítulos que você criou. Incorporar seu feedback e também mantê-lo em mente para o conteúdo que você está trabalhando. Este processo irá reduzir significativamente a carga de trabalho para o fim do projecto.

Depois de ter criado um anteprojecto, você pode apresentá-lo ao seu gerente, editor, especialista no assunto e também alguns desenvolvedores que pode lhe dar mais feedback. Obter a opinião de todos e incorporar as alterações necessárias. Mantenha uma cópia de cada projecto, assim você pode voltar e recuperar as informações excluídas, se necessário. Coloque-se no lugar do leitor e passar a documentação e fazer as seguintes perguntas: Você compreende os conceitos fundamentais? Será que a informação progredir de uma maneira lógica? Será que o interesse conteúdo e educá-lo? Se a resposta a estas perguntas for sim, você conseguiu seu objetivo.