Como Documentar

Como redigir e manter documentação!

Como documentar?

Objetivo

  • Preparar o terreno para documentar as próximas oficinas do Diabolô.
  • Documentação como mensagem para o futuro: questão da memória, de processos de grupos.
  • A documentação embora seja muito importante, muitas vezes fica para o segundo plano, por falta de prática, preguiça, etc.

Metodologia

Três momentos para a oficina:

  • O que é importante documentar numa conversa/oficina/reunião;
  • Quais ferramentas existem para fazer essas documentações;
  • Formar pequenos grupos de trabalhos para fazer a documentação de hoje;

O que se compreende como documentação?

  • Uma ata de reunião, serve para quem nao esteve na reuniao saber o que aconteceu, e para quem esteve lembrar o que aconteceu. (MEMÓRIA)
  • Documentação não é só documentar manuais de instrução, é também uma ferramenta de preservação da memória;

Metodologia

  • Tentar fazer com que sua documentação tenha sempre cara de “pronta”;
  • Manter um padrao de organizacao, estrutura;
  • Mapa mental: FreeMind; post-it; etc – tente agrupar;
  • Tópicos, que atraem outros tópicos;
  • Podemos usar o hipertexto (textos que se referenciam entre si) e uma documentação modularizada facilitando as buscas;
  • Organização por tópicos, subtópicos indice desses tópicos e subtópicos;
  • Como organizar as pastas? Não há um modelo rígido, cada um organiza como prefere;
  • Idéia para o blog do Diabolô: apresentar as metodologias que cada um usa;
  • Estrutura sequencial da informação;
  • Arquivística não conseguiu resolver isso, pois as tecnologias tornam-se rapidamente obsoletas, pois somos refém da Indústria que trabalha com a lógica da obsolescência programada; antes eram disquetes, depois cd, pen drive, nuvem e por aí vai;
  • NUVEM: Você pode manter suas coisas na nuvem, mas tenha SEMPRE uma cópia com você, para não se tornar refém da empresa;
  • Questoes: durabilidade, acesso, histórico, como manter essa documentacao em meio a obsolecencia programada, como fugir do determinismo tecnologico;
  • Índice Remissivo;
  • Guia de referência rápida (cheatsheet); passos;
  • Dificuldade para achar informação que as pessoas em geral consideram mais básicas e por isso ignoram ao longo de outras documentações;
  • Encorajar as pessoas a lerem a documentação mesmo as mais difíceis.

Tradução

  • Quer aprender um idioma? Tente traduzir uma documentação :)
  • Para isso, não esqueça de olhar a licença de cópia que será usada.
  • Fique atento também em qual versão da documentação que você está traduzindo e indique essa informação na sua tradução.
  • As vezes pode ser também interessante criar a sua própria documentação e referenciar a da gringa na sua, ou invés de apenas traduzir uma já existente em outra língua.

Dicas para se escrever uma boa documentacao

  • Quebrar o bloqueio mental de fazer a documentação;
  • Não existe essa idéia de que só pessoas super fodas podem fazer documentação, ou desenvolver softwares por exemplo; qualquer pessoa pode escrever documentação, a pratica ajuda a criar confiança;
  • Estrutura: não precisa ser uma estrutura truncada, pode ser poética e criativa;
  • Evitar linguagem implícita – a documentação deve ser agradável e clara;
  • Piadas, analogias, brincadeiras ajudam a deixar a documentacao mais leve;
  • O que abordar;
  • Contextualizar: o que, quando, como, onde e por que?.
  • Literatura explicita;
  • Evitar ambiguidade nas descrições das recomendações;
  • Documentação deve ser utilitária e fácil de ser compreendida;
  • Desafio cultural: não é bom fazer documentações direcionadas a um tipo específico de público; não deve ser restrito a subculturas, por exemplo;
  • Mais fácil modularizar a documentação, organizando em unidades independentes – facilita as buscas e facilita a utilização de caminhos não previstos;
  • Dividir parte teórica da parte prática;
  • Evitar documentar coisas que são datadas e tornarão-se obsoletas em curto prazo; alternativamente, indicar como obter tal informação.
  • Manter a documentação no servidor e na máquina também (ter várias cópias), pois o servidor pode cair e você pode ficar sem acesso a ela;
  • Não é bom mandar as informações documentadas apenas por e-mail, pois dificulta os processos de buscas; Os arquivos se perdem entre o fluxo de mensagens, por isso é bom tê-las arquivada em algum outro lugar;
  • ECOSSISTEMA DE DOCUMENTAÇÃO: Usar as documentações já existentes e contribuir com elas, melhorando-as. Muitas vezes é mais fácil dar continuidade em uma documentação do que ficar criando do zero; mas nem sempre usar uma documentação existente facilita a vida, pode apenas complicar. Cuidados quando lidar com ecossistemas: fazer sempre backup/cópias para preservar a memória;

Documentando

  • Divisão de tarefas facilita o processo de documentação e sua manutenção.
  • Se você documentou, faça backup dessa documentacao;
  • Se você achou uma boa documentação na rede, faça um backup também;
  • Boa prática: Ecologia de Documentações, partir de uma documentação já feita, acrescentando informações, atualizando e removendo informações obsoletas, sempre respeitando licenças;
  • Exemplos de ecossistemas de documentação:
    • Comunidade de Software Livre: para cada software em desenvolvimento há uma página de documentação ou quase sempre há.
    • Wikipédia
  • No caso de atas de reunião: é interessante terminar a reunião com a ata pronta;
  • Jardinagem de documentação:
    • Geralmente não existem jardineirxs de wiki que mantenham a informação atualizada, retirando informações obsoletas e adicionando novas, e não dispersa; as documentações ao longo do tempo tendem a se tornar caóticas. Fazer a jardinagem da documentação facilita as buscas posteriores;
    • Num ecossistema maior, quando sua documentação torna-se popular, é bom ter alguém responsável para fazer uma jardinagem regular;

Ferramentas

Antes de tudo: não seja refém de uma plataforma e/ou tecnologia, ou seja, aprenda a usar múltiplas plataformas;

Cadernos, cadernetas

Wiki

Palavra em havaiano que quer dizer “rápido”: sistema de documentação rápida que ajuda no desbloqueio, pois você já localizou onde escrever e pode deixar-se livre para verborragias :) Problemas do wiki: Vítima de vandalismos

  • Wikipedia: dispõe de uma série de regras e procedimentos que por um lado facilitam a documentação, mas por outro engessam o trabalho coletivo;
  • Existem wikis fechados disponíveis também
  • Ferramentas abertas que estimulam a colaboracao são muito úteis, mas devemos pensar em mecanismos para evitar que conflitos destruam a documentacao.
  • Wikis dispõe de uma ferramenta chamada “caixa de areia” – lugar para vc aprender a usar e fazer “merdas” sem se preocupar;
  • Wikis pessoais sao uma boa opção para quem quiser treinar o uso da ferramenta; na rede social n-1.cc você consegue criar a sua;
  • Próximo da caixa de texto há uma opção “Dicas de Formatação” onde você encontra os códigos para deixar a wiki mais agradável visualmente;
  • DICAS DE SISTEMAS WIKIS:
    • Ikiwiki: como funfa: vc escreve em marckdown no seu computador vc envia o arquivo pra servidor e ele atualiza atualiza. qual eh a vantagem? vc fica com uma cópia no seu computador (tipo um dropbox de documentação).
    • Ḿediawiki: muito complexo, com muitas opções
    • PmWiki: bem mais leve
    • Dokuwiki: tem poucos plugins e temas

Notas:

  • Nem sempre a gente pode escolher o sistema wiki, então se vira nos 30, pois o objetivo é atualizar a documentação;
  • Edite seu texto em txt e não em pacotes office;
  • MarkDown: sintaxe de formatação para wikis; (alguém melhora isso aqui pq eu não soube explicar bem) —> sugestão: quem quer aprender a usar bem wiki, começar no markdown.
  • Voce tem que hospedar em um lugar que vc tem garantia de acesso.
  • Você não pode ser refem da plataforma —> tem que ser um lugar que vc tenha acesso às suas infos e que possa ser facilmente importado para ourt
  • Dificuldade de instalação e quantidade de recursos pra manter a plataforma
  • Comparação de wikis: Wikipedia / Wikimatrix

Etherpad

  • Não pode ser o local final de armazenamento do texto, sempre salve em outro local final;
  • Dilema do Pad: você usa o pad para fazer uma reunião e deixa ele lá, qualquer pessoa que descubra o nome do pad tem acesso às informações;
  • Pad do Riseup deleta pads não acessados em 30 dias;
  • Pad do Saravá, atualmente, não apaga a documentação: cuidado!;

Gobby

FAQ

Há um padrão de títulos para arquivos/pastas/etc que facilite a organização? EX: usar datas? que formato? usar letras maiúsculas e acentos? etc etc

R: Estes arquivos serão manipulados por muitas pessoas? Que usam sistemas diferentes ou não?

  • Uma possibilidade: pasta nome do coletivo > pasta de imagem , pasta de documentos, etc
  • Nunca usar acentos e espaços em branco, para ser compatível com vários sistemas. Ex: pad-diabolo-20120915 (é isso? sim)
  • Incluir data e/ou numero de versões com dois ou mais dígitos, se for primeira versão adotar ‘01’
  • Quando colocar a data tente usar ANO-mês-dia ou anomêsdia: Ex – 20120915
  • No lugar do espaço pode usar “_”
  • Sugestão de pastas, inspirado na divisão do Gnome 3: Area_de_trabalho ou Desktop, Documentos, Downloads, Imagens, Modelos, Musicas, Videos.

Há padrão de atas?

R: Depende da organizacao para qual a ata esta sendo feita.

  • Data e Local
  • Lista de pessoas presentes
  • Informes
  • Pauta que se tornará Ata

Há diferenças em fazer uma documentação offline ou online?

R: Online é melhor para colaboracao,quando trabalhamos com muitas pessoas. Offline é complicada porque apenas uma pessoa pode editar por vez, voce vai precisar de um sistema de controle de versoes para ver o que mudou etc.

Como lidar com Trolls que buscam destruir as documentações?

R: A ação dos trolls limita o acesso das pessoas à documentação, pois se faz necessário incluir senhas, tirar do ar, etc.

Onde disponibilizar a documentação publicamente?

R: depende do projeto para o qual essa documentcao esta sendo escrita, normalmente o wiki, site do projeto, é um bom lugar WikiSpaces

Referências