Da Hacklaviva
A escolha do wiki como ferramenta para a documentação foi natural, já que permite a desejada edição colaborativa e o crescimento à medida das necessidades. No entanto, coloca alguns problemas ao nível da edição, sobretudo para aqueles que estão habituados a editores rich text.
Índice |
Organização da wiki
1. Centralização de toda a informação que diz respeito ao Tema Transparência através do menu de navegação na sidebar com o título Transparência Hackday
2. Itens do menu - Acerca, Galeria, Actividades, Documentação são gerais e transversais a qualquer projecto no âmbito da Transparência.
- Acerca - descreve a perspectiva de Transparência para a comunidade Hacklaviva Porto
- Galeria - lista os álbuns que estão directamente relacionados com as actividades da Transparência e se encontram alojados no repositório geral de fotos do Hacklaviva
- Actividades - dá notícia de palestras, encontros, sessões sobre o tema Transparência
- Documentação - reúne informação geral da Transparência, com destaque para iniciativas (casos de estudo), ferramentas de apoio ou facilitadoras da Transparência, Apps e entidades e organismos muito voltados para acção nesta área. É uma base de trabalho e inspiração para ser alimentada com contributos de todos, bastando o preenchimento dos campos mínimos que permitam a quem consulta avaliar o interesse para si ou para o projecto.
3. Ainda no menu do Transparência Hackday, é possível aceder directamente aos Projectos que estiverem em curso ou já terminados. Ex. Projecto Parlamento. Ao clicar num item do menu que comece por Projecto, entra-se especificamente na área de um projecto e tudo o que lhe diz directamente respeito. Criámos uma estrutura que pode ser melhorada, mas que para já parece satisfazer e possibilitar o trabalho colaborativo da documentação.
4. Estrutura de cada projecto É sempre complicado decidir já que cada projecto pode apresentar necessidades diferentes. Todavia, sempre podemos estabelecer alguns pontos comuns que permita criar uma base facilmente reconhecível por quem chega e deseja ajudar.
- O Projecto - descrição do projecto, grandes objectivos.
- Seguir-nos - informação de contacto e acompanhamento do projecto.
- Equipa - elementos que participam.
- Glossário - explicação de termos mais específicos ou técnicos presente nos vários textos do projecto que possam não ser facilmente compreendidos por pessoas não tão familiarizadas com algumas operações, técnicas, etc.
- To-dos - Lista simples de tarefas feitas, a serem feitas e a fazer, que permita uma avaliação rápida do estado em que se encontra o projecto.
- Registos - descrição em detalhe das tarefas realizadas pelas várias equipas e núcleos, organizadas por grandes áreas de trabalho. Esta segmentação ajuda a quem chega, tomar conhecimento do que se faz em cada área e concluir onde se sente mais confortável para contribuir. Para cada tarefa, foram determinados alguns pontos acerca dos quais é preciso dar informação. Mas o melhor é consultar sempre uma tarefa que já tenha sido lançada e copiar a estrutura. Caso seja necessário personalizar algo, então cria-se o novo campo.
- Gráficos - todo o tipo de esquemas, imagens, gráficos, rascunhos que ajudem a elucidar visualmente o que se pretende ou o que se está a fazer.
- Ideias - apontamentos rápidos de ideias e sugestões do que se acha que pode valorizar ou fazer no Projecto. às vezes são meros esboços que ainda têm de ser trabalhados. Não queremos que as boas ideias nos escapem!
- Fontes - contém todas as referências às fontes utilizadas ao não no projecto. Sempre que encontramos um dataset ou dados que podem vir a ser interessantes, damos aqui notícia e indicamos qual a sua pertinência e se possível como estão organizados e podem ser acedidos e trabalhados.
Criar o registo de uma tarefa
É muito complicado encontrar uma série de campos que tenham sentido face à diversidade de tarefas, mas por outro lado, ajuda a quem consulta e a quem tem de introduzir dados, ter uma lista de elementos que deve indicar. Numa tentativa de encontrar uma fórmula fácil de preencher e útil, estabeleceram-se os seguintes pontos:
- Descrição - Nesta secção, deve apresentar-se a tarefa, objectivos e o que se fez exactamente, se merecer a pena. Pode ser mais ou menos detalhada, dependendo da complexidade e etapas na sua concretização.
- Fontes - Indicar a fonte ou fontes utilizadas dos dados.
- Dados a recolher - A expressão dados a recolher faz sentido nos registo do tipo Recolher, mas não se enquadra nos registos do tipo Tratamento. Aí, quando muito, colocar-se-ia Dados a tratar. Este campo só deve ser preenchido quando fizer sentido na tarefa em questão. Quando aplicável, deve fazer a listagem dos dados que foram alvo da atenção na recolha, tratamento, etc. Se necessário, organizar os dados em grupos e explicar a sua pertinência.
- Dados técnicos - Informação relativa às linguagens, ferramentas e técnicas usadas para conseguir atingir o objectivo da tarefa.
- Repositório - Links para o produto da tarefa no repositório do projecto. Existe um link para o ficheiro com o código, se houver, e um link para o dataset obtido.
- Equipa - Elementos que executaram a tarefa.
Boas práticas
Na wiki
1. Criar os url de novas páginas seguindo a estrutura de árvore, já que isso permite o funcionamento do Breadcrumb no topo da página e ainda possibilita a criação de mapa do site. A forma mais fácild e criar uma página é escrever o url no navegador e clicar enter. Surge a tab "Criar" que devem seleccioanr para gerar finalmente a nova página.
2. Atentar sempre nos conteúdos que já existem e copiar a sua estrutura.
3. Usar a opção Discussão no topo da página para propor alterações e melhorias.
No código
1. Sintaxe a usar na criação dos CSV's
- usar o pipe (|) como separador e não a vírgula
- o quote character deve continuar a ser a aspa recta (")
