Como você está documentando seu trabalho, processos e ambiente?

Você está usando um formato wiki? Em caso afirmativo, qual produto? (MediaWiki, Confluence, Sharepoint etc.)

Você criou uma base de conhecimento? (Documentos curtos orientados a problemas / soluções.)

Que desafios você encontra na criação de documentação que funciona, para que você não seja atendido quando estiver de férias?

Para mim, acho que muitas vezes há uma certa inércia organizacional envolvida na realização da documentação. Parece ser um tipo diferente de pessoa que pode fazer uma tarefa, depois pense em como eles fizeram a tarefa e a descreva para que outra pessoa possa fazer - tipo de força para você "se tornar meta" e nem todo mundo se sente à vontade para fazer isso.

Atualizar

As respostas até agora incluem

• Confluência
• Flexwiki
• Fogbugz
• Mediawiki (com plugins como fckeditor)
• Sharepoint
• TWiki
• Documentos do Word / Excel / Visio
• Scripts documentados

Edit: você não está documentando implicitamente sua rede com seu sistema de monitoramento? Nagios sempre incentivou o uso dos pais directiva para refletir a estrutura da sua rede, eo notes_url directiva é projetado para permitir que você link para um wiki ou outra documentação baseada em browser. Portanto, aqui a "documentação" é dividida entre o "documento ativo" do sistema de monitoramento e a documentação offline mais detalhada em um wiki. Como passo muito tempo olhando Nagios, faz sentido esforçar-se para torná-lo o mais informativo possível.

Comentando sobre as ferramentas.

Tentamos wiki on-line, mas encontramos várias limitações, que podem ter gosto pessoal, mas incluem a estrutura do documento e, mais importante, a necessidade de conexão ao servidor de documentação.

Estar conectado é um problema sério se você estiver offline ou no local (obviamente, você pode atenuar o local com uma conexão SSL segura etc.)

Nosso processo de documentação atual é:

• gerador de html estático
• sintaxe de remarcação
• sistema de versão distribuído

Temos um layout 'formal' para a documentação e que fornece a estrutura para os menus (e o CSS associado para estilo visual etc.)

Gerador estático de HTML

Usamos um gerador de html casa estático baseado no cubictemp e uma série de outras ferramentas: pygments , docutils .

As páginas geradas são (não?) Obviamente feias, já que a maioria de nós / nossos administradores de sistemas / programadores sabe o que é esteticamente bonito, mas tem uma total falta de coordenação na criação de tais.

Mas ele permite / vamos incluir arquivos de configuração, scripts de amostra, pdf, etc, sem ter que se preocupar com a formatação html estragando tudo ou se preocupar com onde encontrá-lo no 'servidor' para download.

Se não for HTML, basta soltá-lo na pasta e adicionar um link de URL.

O HTML fornece uma estrutura 'potencial' para o layout e também fornece 'links' críticos entre itens de conhecimento / conteúdo (além de mecanismos de estrutura de base, como a possibilidade de criar menus, tabelas de conteúdo etc.) Com o HTML, cada usuário agora pode execute um pequeno servidor Web em sua máquina, seja o lighttpd ou algo pequeno, ou simplesmente ative com o Apache ou o IIS.

Todas as nossas máquinas têm o problema de servir html básico e funcionam bem o suficiente para nós.

Sintaxe de MARKDOWN.

Usamos uma versão simplificada de MARKDOWN, Textish e ou reStructuredTEXT para permitir que nossos sucos 'criativos' escrevam documentação sem ter que se preocupar com HTML.

Isso também significa que todo mundo usa seu editor favorito (eu uso o Scintilla no Windows e * Nix), enquanto os outros aqui usam o vi / vim.

Sistema de controle de versão distribuído.

Usamos o Git para 'distribuir' a documentação entre os usuários. Ah, e também usamos a capacidade de versionamento.

A principal vantagem para nós é que todos podemos trabalhar na atualização da documentação sem precisar estar conectado ao servidor e sem ter que publicar trabalhos 'concluídos'. Todos nós podemos trabalhar nas mesmas partes da documentação, ou em partes diferentes, ou apenas consumir as informações.

Pessoalmente, eu odeio estar vinculado a um servidor para atualizar blogs e muito menos wiki. Git funciona bem para nós.

Comentando sobre o fluxo de trabalho

Os wiki parecem ser a "moda" para a disseminação / codificação de conhecimento, mas, como comentado em outros lugares, todos os processos se tornam difíceis de sustentar, e encontrar a mistura de ferramentas que melhor suporta as necessidades de sua equipe e é sustentável levará tempo.

As melhores soluções acabam sendo descobertas e não obrigatórias.

Começamos a usar o DokuWiki onde trabalho.

No site do Dokuwiki:

O DokuWiki é um Wiki compatível com os padrões, simples de usar, destinado principalmente à criação de documentação de qualquer tipo. É direcionado a equipes de desenvolvedores, grupos de trabalho e pequenas empresas. Possui uma sintaxe simples, porém poderosa, que garante que os arquivos de dados permaneçam legíveis fora do Wiki e facilite a criação de textos estruturados. Todos os dados são armazenados em arquivos de texto sem formatação - nenhum banco de dados é necessário.

Achei o Dokuwiki o mais fácil de implementar porque não requer banco de dados e era fácil de configurar. Também havia módulos suplementares que permitiam usar meus logons de conta do Active Directory existentes, em vez de criar contas para todos, o que era uma grande vantagem em relação a muitos outros sistemas wiki que encontrei. ele também possui o controle de versão típico, onde você pode ver quem postou o que onde e tem a capacidade de reverter para uma versão anterior com facilidade, se necessário. Eles também incluem uma página inicial personalizável, na qual é possível alterar facilmente qualquer tipo de conteúdo que melhor se adapte ao seu ambiente.

Doku Wiki ou Sharepoint para outras coisas que se encaixam em um gráfico.

Você se acostuma rapidamente a postar em um wiki e a sintaxe não é tão complexa. É muito fácil organizar informações e encontrá-las mais tarde por outra pessoa.

Uso o visio para criar gráficos para explicações mais claras (exportar como JPEG).

Estamos usando um wiki. De fato, estamos usando o MediaWiki. No topo do MediaWiki, temos a extensão Semantic Mediawiki instalada, que na verdade transforma nosso MediaWiki em algo como um banco de dados de tipo vagamente digitado que podemos consultar com Categoria, título, conteúdo, etc.

Por exemplo, digamos que eu queira ver todos os nomes de rede que são roteados pelo Cluster F. Tudo o que preciso fazer é usar a página Special: Ask para consultar [[Category: cname]] [[destination :: cluster_f]] .. e retornará todas as páginas que são categorizadas como um cname com o destino como cluster_f.

Damos suporte a algumas centenas de clientes muito diferentes, portanto, ter essa documentação em um local central (e tê-la reticulada para que os casos especiais fiquem documentados e vinculados ao todo) é uma coisa muito útil. Obviamente, nossa documentação precisa ser mantida, mas você pode adotar uma abordagem mais 'jardineira' para a manutenção porque o kit de ferramentas do mediawiki para manter um grande conjunto de dados atualizado já está bastante maduro.

Com os plugins certos, o Trac pode se tornar um sistema combinado de tickets e wiki. Isso facilita a vinculação de seus tickets a artigos da wiki e vice-versa.

Alguns plugins que eu gosto:

• Plugin de tickets privados . O Trac é construído como uma base de erros, onde todos os tickets e suas respostas são públicos. Isso não é apropriado para um sistema de tíquetes de TI, mas esse plugin corrige isso.
• Trac WYSIWYG plugin . Vamos ser sinceros, a maioria das pessoas não vai aprender wikisyntax para fazer você feliz. Isso fornece a eles um editor de 'o que você vê é o que você obtém' para tickets e páginas da wiki.

Existem muito mais personalizações para o Trac. Não é difícil configurar e personalizar um sistema Trac ao seu gosto!

No meu trabalho anterior, usei o Twiki. Funcionou razoavelmente bem.

Além disso, costumo automatizar a maioria das tarefas e documentar os scripts (nem sempre com muito entusiasmo, mas ainda assim ...). A documentação de scripts é feita facilmente no processo de projetá-los, portanto, não há sobrecarga real ...

A combinação de ambos (e usando o controle de versão para os scripts) fez o truque bastante bem.

Uma mistura de documentos JIRA, Confluence e Word.

Institucionalização do conhecimento

Começamos com documentos. Em seguida, armazenamos alguns deles nas bibliotecas do Sharepoint. Recentemente, fomos para o wiki do Sharepoint. Eu gosto da abordagem de baixo atrito do wiki em atualizar rapidamente as coisas, embora as wikis do Sharepoint deixem algumas coisas a serem desejadas no suporte a gráficos e na formatação de itens como tabelas. É bom para o texto e o editor interno permite alguma formatação HTML básica e listas ordenadas / não ordenadas. Existem outras alternativas de baixo custo para o Sharepoint.

Também temos uma base de conhecimento informal para nossos tickets de suporte em nosso software de suporte técnico, o Track-It da Numara. Não é perfeito, mas funciona.

Conseguir que a equipe use conhecimento institucionalizado

Concordo com sua avaliação de que a obtenção de conhecimento institucionalizado é apenas uma parte da batalha. Se sua organização e seu pessoal não estão acostumados a "pesquisar primeiro, pergunte em segundo lugar", você descobrirá que a maneira antiga prevalece: todo mundo ainda procura respostas para os gurus formais e informais, e para algumas pessoas sempre será mais fácil perguntar a pessoa ao seu lado do que pesquisar por conta própria.

Lidar com isso envolverá algum gerenciamento de mudanças; como as iniciativas de mudança mais bem-sucedidas que afetam mais do que apenas uma equipe pequena, ajudará a ter apoio e apoio gerencial. Você realmente precisa forjar um novo comportamento em duas direções; alguém precisa capturar o conhecimento e as pessoas precisam usá-lo. Ainda mais difícil é que as pessoas também precisam manter esses dados atualizados.

Apenas algumas idéias: provavelmente precisará haver incentivo na forma de uma política formal, afirmando que tickets e problemas resolvidos precisam ser documentados na base de conhecimento ou wiki antes que possam ser considerados fechados. Além disso, os líderes do conhecimento que normalmente recebem perguntas nem sempre devem oferecer respostas a pedido; eles precisam apontar as pessoas para os wikis e se acostumar a checar lá primeiro. Outra coisa seria disponibilizar dados aos usuários para auto-ajuda, para que o problema pudesse ser resolvido antes de se tornar mais um item que a equipe técnica precisa manipular.

O que seria bom é que nosso sistema de suporte técnico tenha um sistema semelhante ao StackOverflow e ServerFault: ao digitar uma pergunta, o mecanismo de pesquisa encontra itens semelhantes e os oferece, para que os usuários possam vê-los antes mesmo de enviá-los.

Nos meus últimos dois locais de trabalho, usei o Wiki do Sharepoint, além de uma biblioteca de documentos que continha certos documentos (como DRPs e planos de atualização única) que não podem ser facilmente criados como documentos do Wiki. Esses documentos tinham links de dentro do Wiki. O Wiki tem muitas vantagens nessa área, pois muitas pessoas podem editá-lo, o controle de versão é embutido, facilmente pesquisável e acessível etc. Para escrever notas e idéias rapidamente, eu usaria o OneNote ou um quadro branco.

Eu já havia criado algumas bases de conhecimento antes, em formato de fórum (tanto no Lotus Notes quanto no MS Sharepoint), mas devo dizer que raramente as pessoas as procuram para ver se um determinado problema já foi resolvido. Essa solução deve vir desde o primeiro dia com um mecanismo de pesquisa muito forte e eficaz.

Se você deseja criar documentos que possam ser usados ​​durante as férias, escreva-os como se estivesse tentando instruir um de seus pais. Isso não é 100% infalível, mas às vezes ajuda. Depende de quem está lendo.

Sharepoint é bom.

Seus recursos de pesquisa têm a capacidade de indexar quase qualquer tipo de documento, tornando a pesquisa de documentação realmente fácil.

Ele também pode fazer algumas modelagens, o que pode facilitar as coisas se, por exemplo, você tiver uma folha de informações padrão para cada servidor criado.

Ele também pode fazer a versão dos seus documentos, para que você tenha um histórico de auditoria de alterações na documentação.

Além disso, os arquivos contidos nas bibliotecas de documentos podem ser acessados ​​pela Web, no Outlook ou por meio de um compartilhamento não incluso, pronto para uso.

Nós usamos o MediaWiki (com fckeditor) por vários anos, embora eu deva dizer que seria bom se o manuseio de imagens (por exemplo, capturas de tela) fosse mais fácil. E apesar de ter a capacidade de pesquisar é essencial - acho que a pesquisa do MediaWiki frequentemente perde páginas. Talvez seja apenas uma questão de aprender a pesquisar melhor (o que meio que derrota o propósito de ter uma maneira simples para que outras pessoas façam seu trabalho)

No momento, estamos conversando sobre mudar tudo para o MS Sharepoint , embora não seja necessário para o wiki deles. Eu acho que o Sharepoint é capaz de fazer uma pesquisa completa de documentos de uma maneira que negue algumas das vantagens de um wiki, então vamos ver para onde isso vai.

(não estamos ansiosos pelo processo de portar toda a documentação atual :))

Estamos usando um wiki. Claro que a sintaxe demorou um pouco para se acostumar, mas a que estamos usando (twiki) armazena seus dados inteiramente como arquivos de texto. Isso nos permite lê-los facilmente no caso de um desastre, pois podemos restaurá-los para qualquer lugar e pesquisá-los na linha de comando via grep, e lê-los em qualquer editor de texto de que gostamos.

Todo servidor possui uma página, com uma coleção padrão de subpáginas para informações sobre gerenciamento de alterações, inicialização / desligamento e notas de configuração, além de informações sobre DNS, firewall e ativos.

Estamos nos preparando para migrar para uma versão do serviço Sharepoint para tentar nos livrar de uma mistura de documentos do Word espalhados por três servidores e quem sabe quantas pastas. Atualmente, temos uma enorme planilha do Excel que contém hiperlinks para os documentos descritos nela.

Não é a melhor maneira de fazê-lo, mas quando a empresa começou, eles nunca planejaram como lidar com a documentação interna e deixaram para cada grupo decidir como classificar e armazenar sua própria documentação como quisessem. Agora, estamos tentando mesclar um sistema unificado, que será em torno de uma das ofertas do Sharepoint.

Na ONG em que trabalho, usamos apenas arquivos de texto colocados em uma pasta para procedimentos críticos. Pessoalmente, como híbrido de Administrador do Sistema / Desenvolvedor da Web, tenho usado uma base de conhecimento de arquivos de texto espalhados em um diretório em árvore, esse é o meu Memex e escrevo quase tudo nele (pessoal, trabalho etc.). Esse esquema é muito fácil de gerenciar usando o Jedit, um verdadeiro canivete suíço para processamento de texto, eu achei indispensável o plug-in de estrutura de tópicos, o dobramento de código e os recursos de hiper-pesquisa. Tudo isso foi feito com segurança pelo rsync em um servidor remoto acessível por ssh.

Junte isso à extensão Makelink Firefox e você terá o gerenciador de favoritos perfeito.

Usamos o flexwiki , que é um dotnet e código aberto.

Erm ... que tal Fogbugz? :)

Estamos usando o ScrewTurn para conteúdo e o SharePoint para armazenar documentos / imagens.

Há algumas coisas interessantes aqui - eu gosto da sobre as senhas em um cofre.

Usamos uma combinação de arquivos de texto para pesquisa rápida com grep. E o SharePoint para uma coleção mais organizada de documentação detalhada (diagramas do Visio etc.).

Como clientes do Google Apps (Enterprise), usamos o Paradiso do Google Sites - o "sabor" do wiki deles. Fácil de usar e tivemos uma ótima adoção de administradores e desenvolvedores.

Eu não vi essa pergunta antes de responder a outra pergunta , mas aqui vamos nós.

Usamos várias ferramentas e métodos.

• Especificações funcionais para componentes e software de infraestrutura.
• Dois Wikis de Confluência . Um para documentação corporativa interna (políticas, procedimentos, infraestrutura interna e TI, etc) e outro para nossos produtos de software de código aberto.
• Testes RSpec e Pepino . Nosso software é principalmente escrito em Ruby e praticamos BDD / TDD , para que os testes de especificação controlem o código real e os documentos também.
• Documentação de código embutido. Usamos a marcação RDoc nos comentários do código.
• Gerenciamento de configuração declarativa ( Chef ). Todos os nossos servidores são gerenciados com o Chef, que "se autodocumenta" através de recursos delcarativos em receitas e livros de receitas.

Gostamos do Confluence porque é muito flexível e poderoso e possui recursos completos, além de estar vinculado ao software de gerenciamento de tickets que gostamos, Jira .

Nas empresas anteriores em que trabalhei, usei uma variedade de ferramentas e métodos e muitos tentaram permanecer com um único recurso abrangente (como um Wiki) para tudo. O problema disso é documentar vários tópicos com uma única ferramenta não adequada para cobrir esse tópico, significa que muitas coisas não serão documentadas, porque é difícil migrar as informações. Como um geek do Unix / Linux, acredito que cada tarefa requer uma ferramenta específica, e essa ferramenta deve se encaixar muito bem nessa tarefa.

Esta pergunta é muito bem uma duplicata desta e mudei minha resposta para lá.

Eu faço a maior parte da documentação da minha empresa e o formato que foi estabelecido quando comecei a trabalhar aqui foi o MS Word para originais editáveis, exportados para PDF para lançamentos gerais somente leitura. Funciona razoavelmente bem para projetos em que apenas uma pessoa está atualizando o documento e, como essa pessoa geralmente sou eu, a gerência não vê necessidade de mudar.

Começamos a documentar nossos bugs e tarefas futuras com o Trac , enquanto usamos uma extensão "Revisão por pares" para revisões de código. Essa foi uma grande aceitação da nossa equipe, porque é simples colaborar e fácil de navegar. Alguns outros membros da equipe expressaram o desejo de começar a colaborar mais com especificações, procedimentos de teste e manuais, por isso estamos analisando o DocBook / XML exportado para PDF para documentação pública como manuais e as páginas Trac WIKI para documentos internos, como especificações e procedimentos de teste.

Na minha opinião, os maiores problemas ao escolher um formato de documentação são:

1. É fácil criar?
2. É fácil de manter?
3. É fácil manter se alguém o escreveu?
4. Pode ser exportado / convertido para outros formatos sem muito aborrecimento?

1-3 facilitam minha vida e são importantes para produzir documentação rapidamente, sem enlouquecer. Eu acho que o quarto é o mais importante para o cliente, porque os formatos mudam continuamente. O formato Microsoft Word 2003 não estará disponível para sempre, nem nossa implementação atual de PDF. Eu preciso garantir que todos os nossos clientes possam ler nossos documentos, independentemente do sistema operacional ou do leitor de documentos escolhido.

Usamos o MediaWiki com vários plugins, incluindo o SemanticMediaWiki. O SMW é bom porque transforma nossa instalação do MediaWiki em um grande banco de dados relacional de formato livre que pode ser consultado à vontade. Precisa saber em qual servidor o site está? Visite sua página. Precisa saber quais sites estão hospedados em um servidor? Execute uma consulta e ela selecionará os nomes das páginas com base na tag apropriada na página de cada site.

Não responderei com um sistema de documentação que usei, mas com algo que já vi usado e que acho muito bom: http://stackexchange.com/

stackexchange é a plataforma de perguntas e respostas executada sob falha de servidor (bem, tecnicamente, não é exatamente a mesma coisa, mas, para nosso propósito, podemos assumir que é a mesma).

O Fogbugz usa .

Há uma publicação interessante no blog de um funcionário do Fogbugz, onde encontrei estas citações:

Para todos os fins fora das especificações do produto, acho que os wiki corporativos e as formas de discussão foram um golpe fatal.

...

Desde que começamos a usar o FogBugz.StackExchange.com como nossa plataforma de suporte, nunca respondi a mesma pergunta duas vezes. Temos até um servidor SE interno que usamos para perguntas e respostas não públicas, e os mesmos princípios se aplicam a ele.

Eles usam o stackexchange para a base de conhecimento voltada para o cliente e a base de conhecimento interna.

Estou interessado em ver se essas plataformas de perguntas e respostas sobre troca de conhecimento substituirão os wiki corporativos.

No meu empregador anterior, usei arquivos do Word, Excel e Visio coletados juntos em uma pasta. Uma cópia impressa de tudo estava guardada em uma pasta na minha mesa. Eu era a única pessoa de TI, então havia pouca necessidade de mais alguém ter acesso às informações.

No meu atual empregador, usamos o Macola ES da Exact Software, mas ainda prefiro escrever minha documentação no Word e carregá-la no Macola como anexo do que usar o editor de documentos embutido.

No meu local de trabalho, larguei o ScrewTurn Wiki em um de nossos servidores de desenvolvimento Windows e o vinculei ao nosso SQL Server. Funciona muito bem, roda rapidamente e principalmente fica fora do nosso caminho para a documentação. Nas duas semanas desde que foi implantado, já adicionamos cerca de 60 páginas de informações, e é apenas para nossa equipe (~ 10 pessoas).

Até o momento, mantemos informações sobre projetos atuais e passados ​​e começamos a adicionar informações sobre os aplicativos, como como construí-los do zero, URLs e outras informações importantes para os desenvolvedores que são novos na equipe.

Uma das minhas páginas favoritas no wiki tem sido a página de ferramentas e bibliotecas. Lá, começamos a adicionar informações sobre nossas ferramentas e bibliotecas favoritas de produtividade que usamos muito, um exemplo do qual é grepWin para pesquisa de texto no Windows.

Eu recomendaria totalmente verificar toda a gama de wiki disponíveis e encontrar uma que se adapte ao uso, funcionalidade e ambiente de implantação pretendidos. Eu escolhi o ScrewTurn porque é fácil de usar e tínhamos muito espaço livre em nosso WinServer local, mas o YMMV.

Estamos usando o Confluence como wiki e sharepoint para documentos em alguns casos. Acredito que o formato wiki online é o preferido quando você precisa compartilhar essas informações amplamente e o que é muito mais importante quando os documentos são editados e atualizados com muita frequência. Então, acho que é melhor colocar os artigos da base de conhecimento no wiki.

No momento, estamos movendo nossas informações de vários documentos espalhados pela rede para dois locais:

1. Um wiki disponível em nossa intranet
2. Uma cópia das informações relacionadas a um servidor específico nesse diretório de servidores / raiz.

Para diagramas de rede, Network Notepad .

Além disso, ao gravar o quê, lembre-se de registrar por que algo está configurado como está. Isso ajuda a impedir que idéias que parecem boas sejam transformadas em erros.

Descobrimos que o MediaWiki teve um início lento, mas depois que as pessoas fora da TI descobriram como era fácil adicionar comentários, alterações, edições etc., tornou-se indispensável. Os desenvolvedores estão usando-o para documentação interna, departamento de instalações. para publicação de avisos etc. Ele cresceu além de ser apenas uma ferramenta de documentação de TI.