Padrões do setor para documentação interna?

Question

A organização para a qual trabalho é crescente e com esse crescimento vem a maturidade e com essa maturidade surge a necessidade de documentar melhor.

Hoje é uma mistura de diretórios, wikis, OneNotes e nada disso é padronizado em termos de forma ou conteúdo, rotulagem ou mesmo conhecimento de onde procurar qual item. Cada equipe é diferente e até mesmo os indivíduos nas equipes não aderem necessariamente a nenhum padrão de equipe.

Não estou procurando produtos específicos ou conselhos sobre o que padronizar. Também estou mais interessado em quais padrões as organizações / empresas maiores estão usando.

    

Answer 1

Existem vários padrões ISO para documentação técnica, conforme listado em en.wikipedia.org/wiki/DocumentationTechnical . O artigo da Wikipedia sugere que eles são específicos de certas indústrias (e os padrões ISO reais não estão facilmente disponíveis no domínio público AFAIK) ...

Para desenvolvimento de software, por exemplo, IEEE 12207 também rege a documentação.

Mas a coisa toda com documentação interna é que muitas vezes a maioria das organizações quer fazer o que for especificamente para elas, em vez de seguir padrões externos.

Antes de tentar impor um padrão, você já está à frente da curva se e quando:

• a documentação é realmente gerada
• a documentação está disponível para aqueles que precisam dela (ela pode ser pesquisada e encontrada quando a necessidade surgir e também pode ser acessada ...)
• a documentação é mantida e atualizada

E como um departamento de TI, em vez de tentar criar e / ou aplicar padrões específicos, basta facilitar, por instanciação, fornecer um bom mecanismo de busca interno

    

Answer 2

Não conheço nenhum padrão do setor, mas a melhor experiência que tive com a documentação interna foi em uma organização que tinha uma equipe dedicada responsável pelo suporte e curadoria responsáveis por escrever toda a documentação em si.

O sistema que eles usaram era um wiki, mas qualquer fonte única de verdade deveria funcionar. Eu diria que deveria suportar o versionamento de forma nativa. Não há nada que eu não possa suportar mais do que as pessoas enviando por e-mail com documentos do Word com várias páginas dedicadas a um registro de alterações de documentos. Se você precisar de uma cópia da revisão atual, deve ser fácil exportar da fonte como um PDF.

A maioria da equipe tinha formação em tecnologia. Eles eram responsáveis pelo desenvolvimento de modelos para tipos comuns de documentação. Eles ajudariam outras equipes a começar a escrever seus próprios documentos. Eles auditariam os documentos que as pessoas estavam criando e potencialmente os editariam por estilo / consistência. Foi glorioso.

E, vamos ser honestos, escrever uma boa documentação requer tempo e esforço. Não há nenhuma ferramenta mágica que facilite isso. As PMEs de um determinado sistema devem estar dispostas a escrever (e manter atualizada) a documentação de seus vários sistemas / projetos.

    

Answer 3

Eu não posso falar sobre organizações particularmente grandes, mas em qualquer tamanho, criando um padrão razoavelmente bem organizado e aplicando-o (dentro do razoável) para que toda essa documentação esteja em uma plataforma, de preferência uma com acesso controle e recursos de pesquisa é um grande passo à frente.

Em relação aos padrões legítimos e à prática padrão, encontrei este post detalhando como você pode desenvolver o seu próprio, e quais fatores podem precisar explicar, bem como citando padrões ISO relevantes.

Eu acredito que isso é tudo o que existe, até onde os padrões são definidos, então tudo se resume a criar padrões adaptados às necessidades da sua organização.