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¶

• Vantagens: põe no bolso, não usa bateria; ajuda a documentar coisas bem na hora. Um produto revolucionário.

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¶

• 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¶

• Documentacao da Rede Indymedia – docs.indymedia.org
• Documentacao da Rede Indymedia Brasil – docs.indymedia.org/Local/CmiBrasil
• Documentacao Guia Foca Linux – www.guiafoca.org
• Wiki do Debian – wiki.debian.org
• Wiki – pt.wikipedia.org/wiki/Wiki
• MediaWiki – www.mediawiki.org/wiki/MediaWiki
• PMWiki – www.pmwiki.org
• IkiWiki – ikiwiki.info
• Markdown – pt.wikipedia.org/wiki/Markdown | daringfireball.net/projects/markdown/sy... | github.github.com/github-flavored-markd... | Esse aqui é bem bacana pra treinar, pois você escreve na linguagem markdown e ele automaticamente mostra como o texto está ficando: www.tiagobutzke.com/markdown esse é um editor pros seus fins mais divertidos dillinger.io
• Gooby – en.wikipedia.org/wiki/Gobby – gobby.0x539.de/trac
• Links: links.sarava.org