Existem padrões/convenções usados ​​por redatores técnicos de TI?

Question

TL:DR? Bem aqui:

Além de contratar ou terceirizar um redator técnico, existem padrões/convenções/práticas básicas que os redatores técnicos empregam em seu ofício que podem ser aprendidos para criar documentação de TI adequada e manter essa documentação ao longo do tempo?

---

Ao escrever várias documentações para uso interno de TI e uso externo por nossos funcionários, ficou claro que todos os nossos funcionários têm seu próprio estilo no que diz respeito à documentação.

Com base em nossos documentos de qualidade e documentação controlada, a TI utilizou vários modelos para SOPs, WIs e vários formulários usados ​​para documentos de qualidade de TI. Esses documentos, embora não sejam necessariamente úteis para as operações diárias de TI, ajudam os funcionários e a empresa com questões de RH de TI, conformidade, etc. e geralmente são bem escritos, bem definidos e seguem pelo menos os modelos do departamento de qualidade. e padrões de documentação (como versionamento, ECNs, etc.)

Mas a nossa redação real de documentos de TI ainda carece de uma verdadeira convenção/padrão. Alguns usarão ferramentas de terceiros como ScreenSteps, outros simplesmente usarão o Word e criarão um esboço simples como:

1. Abrirapp
2. Clique em `Iniciar Guerra Termonuclear Global"
3. ...
4. Lucro

A documentação interna de TI é realmente pior, com base no que o funcionário ou consultor considerou suficiente no momento para refrescar suas próprias memórias ou no editor de sua preferência (vi, word, excel, powerpoint, guardanapo, wiki interno). O problema surge quando um funcionário sai ou está de férias e há uma confusão para descobrir até mesmo informações básicas. Às vezes, apenas a data do arquivo é um indicador se os dados ainda são relevantes ou não.

Embora um esboço simples, capturas de tela reais ou até mesmo vídeos completos em HD sejam muito bons, não temos um redator técnico de TI real na equipe e não podemos deixar de pensar que estamos faltando nesta área.

Poderíamos criar nossos próprios padrões para nossa documentação junto com modelos aprovados? Sim, mas por que reinventar a roda? Se tais padrões e convenções já existirem dentro da "guilda" do Redator Técnico, seria melhor seguirmos essas convenções para que nossa documentação seja clara, concisa e profissional.

Para evitar ser informado"Pesquise no Google", procurei sites que mostravam algumas práticas de formatação e enquanto este SF Q:Plataformas de documentação de TIajuda a encontrar plataformas e software para lidar com a escrita, mas não discute se realmente existem padrões na indústria.

Portanto, além de contratar ou terceirizar um redator técnico, existem padrões/convenções/práticas básicas que os redatores técnicos empregam em seu ofício que podem ser aprendidos para criar documentação de TI adequada e manter essa documentação ao longo do tempo?

Answer 1

Escrever é uma disciplina.

Eu fiz muito isso, e tenho o máximo de conhecimentos básicos que uma pessoa não treinada pode obter, sem que a documentação seja uma parte importante do meu trabalho. O tempo me mostrou que documentação que eu produzo será realmente lida e o que irá para a prateleira do Eternal TL;DR. Esta é na verdade a regra número um para escrever qualquer coisa:

Conheça o seu público.

O público da documentação interna de TI somos nós mesmos. E administradores de sistemas? Quando buscamos documentação, especialmente documentação interna, procuramos:

• Localizável
• Apresentação
• Ao ponto
• Me leva para onde estou indo

A explicação de cinco parágrafos sobre o histórico de um sistema será ignorada em favor da lista de verificação abaixo dela, porque estamos com pressa e só precisamos terminar isso. E se o aviso aíse você executar certas etapas fora de ordem, todos os seus backups serão apagadosestá naquele bloco de texto ignorado, talvez deva ter alguma formatação que chame a atenção ou talvez inclua essa parte na lista de verificação também.

Documentação do Processo

Este tipo de documentação descreve uma maneira de fazer algo. É o mais fácil de produzir para uma pessoa não treinada, pois na maior parte é apenas escrever uma série de passos a seguir. Na minha experiência, uma boa documentação de processo tem as seguintes características:

• Contém uma lista de verificação.
• A lista de verificação está na mesma página que um breve resumo de quando e por que a lista de verificação é executada.
• Abaixo da lista de verificação, ou em uma página vinculada, há um documento mais longo que descreve a teoria por trás da lista de verificação e as variações que podem ser encontradas.

Você deseja que haja a lista de verificação a seguir e pelo menos o primeiro nível de etapas de solução de problemas já na página (ou a um clique de distância), caso sejam necessários.

Este é um formato familiar se você já leu os artigos da base de conhecimento da Microsoft: resumo, correção, detalhes, sistemas afetados. Há uma razão para isso.

Guias de solução de problemas

Isso é mais complicado do que a documentação do processo porque você precisa codificar árvores de decisão em sua documentação. Uma lista de verificação simples provavelmente não será suficiente, mas uma lista de verificação ramificada, que usa links para outras listas de verificação, é bastante viável. As mesmas regras se aplicam a este tipo de documentação que os documentos de processo:

• Seja breve, não afogue o leitor em detalhes.
• Seja claro sobre quais são os pontos de decisão e onde seguir para as ações subsequentes.
• Salve os conhecimentos técnicos aprofundados para a Documentação de Arquitetura.

Um guia de solução de problemas pode ser uma grande história de Escolha sua própria aventura ou uma grande lista com marcadores de tudo que deu errado em um sistema e o que o corrigiu.

Documentação de Arquitetura

O tipo mais difícil de produzir, já que foi projetado para ser um material de referência que só será referenciado por novas pessoas que desejam entender essa coisa complexa em que acabaram de encontrar.

A documentação arquitetônica é o documento do porquê. É por isso que este sistema está sendo usado e não aquele sistema, como eles estão conectados com esse outro sistema e o que fez essa conexão funcionar da maneira que funcionou. É a documentação que você deve escrever assim que souber como é sua configuração de produção e atualizá-la conforme as alterações forem feitas.

Em termos de formato, tenho que recorrer aos especialistas neste assunto.

---

Uma boa documentação também é mais do que apenas o modelo e o formato para eles, uma aparência unificada é boa e melhora a legibilidade, mas também precisa de outras coisas.

Atualizações regulares

Adquira o hábito de revisar a documentação que você já possui para ter certeza de que ainda está boa. A lista de verificação para a versão 1.17 pode não ser boa para a versão 1.26, é hora de atualizá-la. As listas de verificação mecânicas precisam de mais atualização, pois mesmo as menores alterações na interface do usuário podem atrapalhar tudo.

Dedicando 10 minutosuma semanaexaminar a documentação e identificar coisas que precisam de limpeza pode fazer coisas incríveis.

A documentação arquitetônica precisa ser revisada periodicamente por alguém que conheça o sistema. Como mencionei, estes são documentos raramente usados, mas muito úteis quando você realmente precisa deles. Você não quer o documento que descreve como o cluster de serviços de impressão do campus está conectado ao NetWare quando a migração para o Windows aconteceu há 3 anos.

Detectável

Isto é o mais difícil de acertar porque depende em grande parteondevocê está armazenando sua documentação.

O que dizemos a qualquer pessoa que venha ao ServerFault com uma pergunta?

O que você já tentou?

Seguido em breve por

O maior sucesso no Google resolve seu problema. Talvez você devesse tentar isso.

Procuramos a nossa documentação, não vamos à estante. O repositório de documentação precisa ser tão pesquisável quanto o Google, ou iremos apenas para o Google.

O Repositório Central de Guardanapos é um lugar ruim para documentação, pelo menos se não tiver um índice online (e não terá). Um wiki simples é melhor, pois a maioria deles inclui pelo menos pesquisa básica de texto. Um sistema melhor é aquele que permite que as tags sejam pesquisadas além do texto completo para focar melhor a pesquisa nas áreas-alvo.

Se você estiver trabalhando com um repositório de documentos compatível com tags,padronize suas tags. Basta olhar a lista de tags ServerFault algum dia para ver por quê. Os usuários não deveriam ter que memorizar as oito permutações deVMwareapenas para encontrar o que procuram. Isso exigirá esforços ocasionais de remarcação.