Oficina documentação

Motivação

Para elucidar a importância da Documentação e de uma Documentação de qualidade, realizamos uma atividade lúdica. A proposta era dividir o grupos em 4 grupos com o objetivo de replicar um avião de papel complexo . Cada grupo ganha um item diferente que deve servir como base para replicar o avião:

  • 1 avião de papel pronto, porém com suas dobras coladas (sem documentação e fechado)
  • 1 avião montado normalmente (livre, mas sem documentação,será necessário engenharia reversa);
  • 1 tutorial escrito apenas com palavras, porém sem desenho (representa uma documentação ruim).
  • 1 tutorial com desenhos, indicações de dobras, mas ainda assim confuso (representa quem apenas libera os arquivos mas não explica como usá-los juntos);

A ideia da atividade é instigar a importância da documentação. Não basta apenas ser livre, nem aberto, nem sempre a engenharia reversa é factível. Não basta ter alguma documentação, ela deve ser de qualidade, caso contrário as pessoas não irão conseguir replicar.

O que é?

A Documentação é um registro do projeto. Seu histórico, contexto, montagem, desenvolvimento, etc. A documentação é um conjunto de arquivos que permite alguém entender o objetivo, proposta e uso do projeto, saber replicar, adaptar, enfim, que permita que o projeto seja usado, estudado, modificado e distribuído.

Incluso na documentação, é importante usar softwares livres e formatos de arquivos livres e abertos, que permitam a modificação.

Importância

Uma boa documentação é necessária para garantir que o projeto possa ser:
  • Replicado;
  • Adaptado;
  • Acessível (através das ferramentas livres udasdas);
  • Escale;
  • Colaborativo;
  • Emancipatório

Como fazemos

Nossa metodologia é visa promover as 4 liberdades básicas do Software Livre: usar, estudar, modificas e distribuir.
Acreditamos que, para isso, todas as ferramentas de desenvolvimento e documentação devem ser abertas e livres. Segue uma lista de algumas ferramentas usadas pela equipe do CTA.

Documentação deve estar disponível online

Para que o acesso a documentação seja amplo, é necessário que os arquivos, tutorias e informações sobre o projeto estejam disponíveis online. Pode-se usar plataformas bem conhecidas, como o Gitlab, Instructable, Wevolver, plataformas específicas, como o Farmhack. O Gitlab é especialmente importante por permitir a criação de wiki, tarefas e gitbook. Pode-se também ter o próprio site, como é o nosso caso. Nossa documentação segue o Modelo de Documentação , que está em discussão no fórum . Uma alternativa para gerenciamento de projeto é o Sandstorm

Desenho de placas de circuito impresso

  • Kicad
    • Tutorias e dicas podem ser encontrados aqui
      e aqui
      . Um fórum para dúvidas pode ser encontrado aqui

Desenho de peças (CAD)

Texto, planilhas, apresentações

Para textos, existem diversos softwares simples como o emacs, gedit, etc. Para quem precisa de um pacote de escritório, o LibbreOffice é uma boa opção.

Licenças para documentação e para hardware

Como funciona as licenças de hardware no Brasil?

O cenário do hardware aberto e livre no Brasil, assim como no mundo, é recente carrega consigo muitos questões em aberto. Uma delas é: se eu liberar meu hardware, alguém pode patentear e retirar os direitos? Segundo o advogado Pedro Ramos, uma patente no Brasil só deve ser feita para inovações, ou seja, objetos e ideias que nuca tenha sido divulgadas. Por isso, se seu projeto for bem documentado e estiver disponível online, não poderá ser patenteado. Descubra mais sobre o assunto na conversa entre o Pedro Ramos, Bruce Perens e Javier Serrano, que ocorreu no e-HAL 2016.

Registro e Encaminhamentos

O grupo sentiu a necessidade de usar o Gitlab como ferramenta de documentação. Por isso, faremos uma atividade sobre Git no dia 28/07.

tutorial_aviao_1.jpg - foto do tutorial para montagem de avião usado na oficina de documentação (63.3 kB) Marina de Freitas, 19/07/2017 13:50

tutorial_aviao_2.jpg - foto do tutorial para montagem de avião usado na oficina de documentação (94.2 kB) Marina de Freitas, 19/07/2017 13:50

tutorial_e_avioes.jpg - foto dos tutoriais para montagem de avião e dos aviões usados na oficina de documentação (101.9 kB) Marina de Freitas, 19/07/2017 13:50

atividadeaviao1.jpg - fotos da atividade lúdica (172.5 kB) Marina de Freitas, 19/07/2017 17:56

atividadeaviao2.jpg - fotos da atividade lúdica (183.4 kB) Marina de Freitas, 19/07/2017 17:56

atividadeaviao3.jpg - fotos da atividade lúdica (77.9 kB) Marina de Freitas, 19/07/2017 17:56

atividadeaviao5.jpg - fotos da atividade lúdica (147.6 kB) Marina de Freitas, 19/07/2017 17:56

atividadeaviao6.jpg - fotos da atividade lúdica (180.2 kB) Marina de Freitas, 19/07/2017 17:56