Discussão sobre o Modelo de Documentação Padrão

Added by Renan da Silva over 5 years ago

Espaço para discutir mudanças no Modelo de Documentação Padrão.


Replies (5)

RE: Discussão sobre o Modelo de Documentação Padrão - Added by Renan da Silva over 5 years ago

Sistema de Referências

Eu alterei o sistema de referências para o modo de footnote do Textile.

Antes, o modelo indicava como fazer a referência na sessão "Referências", mas não como citar a referência no texto. Agora, a citação, no texto, é "clicável" e leva à referência clicada na sessão de referências. (Botei as citações em partes aleatórias do texto).

Diferenças: http://cta.if.ufrgs.br/projects/suporte-cta/wiki/Modelo_de_Documenta%C3%A7%C3%A3o_Padr%C3%A3o/diff?version=3&version_from=2&commit=Ver+diferen%C3%A7as

h2.RE: Fórum do GOSH 2017 - Added by Marina de Freitas over 3 years ago

Fórum do GOSH 2017

Fórum da Seção 1: https://forum.openhardware.science/t/documentation-session/290

Fórum da Seção 2: https://forum.openhardware.science/t/documentation-and-sharing/302/2

Os comentários abaixo estão em: http://cta.if.ufrgs.br/projects/suporte-cta/wiki/Anotações_da_Marina/

Lista de documentações que podem ser estudadas

Sentimos a necessidade de escrever um guia menor, de fácil leitura. Um guia internacional e "unificado" de documentação, para termos padrões bem estabelecidos e facilitar a colaboração.
Acredito que existam dois tipos de documentação: Documentação de desenvolvimento e Documentação da versão final (os nomes não precisam ser esses).
A Documentação de Desenvolvimento não é aqui a documentação para desenvolvedores, é a documentação do processo de desenvolvimento, como um log, um caderno de laboratório. Ele pode ser feito num fórum, com o uso de tarefas, com o git, mas é fortemente sugerido que não seja uma wiki. O motivo disso é que essa documentação deve ser fácil, deve ocupar o menor tempo possível da(o) desenvolvedora. Essa documentação pode contar fotos, desenhos, pode e vai ser mais gostoso se for em primeira pessoa, pode ser bem pessoal. Essa documentação ajuda na organização do projeto, caso ele seja patenteado durante o processo de documentação serve como prova de que já estava sendo desenvolvido, permite a colaboração, e mostra como as pessoas erram muito antes de chegar a um produto final.
A Documentação da Versão final é aquela para o projeto, hardware, software, ferramenta, artigo pronto, para a versão terminada. Para uma ferramenta de hardware de uma determinada versão as quatro divisões que eu sugero são Montagem, Uso, Ensino e Racional. A Documentação de Montagem é aquela que ensina como encaixar as peças, seja como fazer o circuito, as peças mecânicas, todas essas partes. Ela não entra nos detalhes do porquê de cada decisão, informa apenas o suficiente para que alguém possa replicar o produto. A Documentação de Uso é aquela que, dado o produto montado, ensina a operar, usar os softwares, apertar os botões certos. A documentação de Ensino é aquela que traz os materiais educacionais associados aquela versão do produto, ou até mesmo uma discussão sobre suas potencialidades. A Documentação Racional é a que traz a reflexão sobre cada decisão, dos porquês de cada filtro, componente, tamanho, e formato do produto. A calibração pode entrar no racional também.
A licença deve estar bem clara e visível.
A wiki do projeto pode ser feita mesmo antes dele ficar pronto, porém estará vazia.

Criar uma maneira de fazer Easy real-time documentation. Mundializar a documentação ( protocolos, padrões, formatos comuns).
Será que o CTA precisa usar outro tipo de documentação que não seja o site? O git já é usado, e é o mais usado nesse sentido, então talvez isto seja o suficiente, por enquanto, nesse caminho de mundializar a documentação. (mas já não faz isso com o git?) Será que devemos modificar o modelo de documentação do CTA (proposta será documentada em breve)?

Proposta de Modelo de Organização de Projetos - Added by Marina de Freitas over 3 years ago

Proposta de Modelo de Organização de Projetos

Segue a minha proposta de Modelo de Documentação

Modelo de Documentação Padrão

Segue modelo de documentação inicial de projeto. Cada item pode estar presente de acordo com necessidades do projeto. Cada item e seção deverão ser avaliados se são apropriados ao projeto em cada fase de seu desenvolvimento. Se muito extensos, alguns itens deverão ser realocados em páginas separadas.

Título do Projeto

Frase de impacto que ilustre a importância do projeto (desenvolvimento, uso/aplicações).

(Inserir aqui foto que ilustre o projeto.)

Descrição do Projeto

Inicia-se uma descrição breve do projeto, de um ou dois parágrafos. Usos e aplicações1.


Principais Características

  • Características listadas vão aqui;
  • Aqui vai a outra característica do projeto;
  • Mais uma propriedade do projeto.

Histórico

Tenho minhas dúvidas sobre a existência desse item, nunca vi ninguém realmente usando ele. Talvez fosse mais apropriado e eficiente focar as energias nas tarefas e encontros periódicos

Data Evento
06/01/15 Início da discussão sobre padronização
07/01/15 Criação do esboço de modelo

Próximos Passos

O mesmo do item acima. Talvez eles possam ser opcionais. Lembro de usar o próximos passos para registrar ideias, o que talvez possa ser feito no fórum, que é uma maneira mais dinâmica de discutir.
----

Documentação de Desenvolvimento

Descrever qual ferramenta está sendo usada para a documentação e indicar um link para ela.

O que é: A Documentação de Desenvolvimento não a documentação para desenvolvedores, é a documentação do processo de desenvolvimento, que é feita durante o processo de desenvolvimento. Ela pode ser feito num fórum, com o uso de tarefas, com o git, como um log, um caderno de laboratório, mas é fortemente sugerido que não seja uma wiki. O motivo disso é que essa documentação deve ser fácil, deve ocupar o menor tempo possível da(o) desenvolvedora. Essa documentação pode contar fotos, desenhos, pode e vai ser mais gostoso se for em primeira pessoa, pode ser bem pessoal.
Essa documentação ajuda na organização do projeto, caso ele seja patenteado durante o processo de desenvolvimento e essa documentação serve como prova de que já estava sendo desenvolvido, permite a colaboração, mostra como as pessoas erram muito antes de chegar a um produto final, e servem como material para que as(os) novas(os) colaboradoras(es) sejam mais facilmente introduzidas no projeto.

Ferramentas de documentação: fóruns, tarefas, git
Exemplo: tarefa emm, física e música

A documentação dos encontros períodicos também é uma maneira de documentação de desenvolvimento

Gerenciamento de Tarefas

As tarefas são uma ferramenta de organização que facilita o desenvolvimento colaborativo. Permitem que novos membros possam mais facilmente compreender o processo de desenvolvimento do projeto.
Elas estão divididas em "Defeito", "Suporte", "Desenvolvimento" e "Documentação".

Fóruns

Os fóruns são um espaço para discussão, troca de conhecimento e feedback de usuários. Por isso, é aconselhável que os seguintes fóruns sejam criados: "Uso", "Desenvolvimento" e "Documentação". Conforme a necessidade do projeto, outros fóruns podem ser criados, como "Grupos de estudo" ou até mesmo "Assuntos diversos".
O espaço do fórum é também onde as reuniões do grupo devem ser registradas, o que chamamos de "Encontros periódicos".

Encontros periódicos

É aconselhável que cada projeto tenha pelo menos um encontro por mês e que este encontro seja sempre registrado no fórum "Encontros periódicos" do próprio projeto. Como especificado no modelo de gestão de projetos do CTA . (muito importante) .
Mais informações sobre os encontros periódicos podem ser encontrados no item abaixo Dinâmicas de Reuniões e Organização.

Arquivos, Documentos e Repositório

Qual a diferença? Em construção;

Documentação do Bloco X Versão n

A documentação da versão é a documentação de uma versão específica, seja de um software, ou de uma ferramenta ou de apenas uma parte dela. Ela pode ser feita junto com o desenvolvimento do projeto, mas só vai estar completa quando o desenvolvimento de uma versão for terminada. Por bloco X entende-se uma parte do projeto, onde X é uma parte como, por exemplo, circuito, ou a estrutura mecânica, ou o software. Em versão, n é um número. A documentação das versões anteriores do Bloco X pode ficar indicada, com menos destaque, aqui.

Wiki

Para edição na Wiki, o Modelo de Documentação Padrão abaixo é o sugerido. Alterações e adaptações as necessidades e especificidades de cada projeto são bem-vindas.

Montagem

Descrição de como construir, montar e encaixar as peças da ferramenta.

Uso

Descrição de como se dá a utilização de produto. Instruções de utilização, configuração e operação.

Racional

Descrição das escolhas de design, escolha de peças, dos detalhes do projeto. Esta seria a conhecida "Documentação para desenvolvedores", aquela que habilita outras(os) desenvolvedoras(es) a estudarem e modificarem a ferramenta

Ensino

Oficinas e tutoriais direcionados para aplicação em grupos por instrutores.
Observação: É produtivo que seja adicionada uma frase ao final de cada tutorial que incentivo o uso dos fóruns como ambiente de discussão, exemplo:
"Dúvidas e sugestão são bem recebidas no fórum." Sendo a palavra "fórum" um hiperlink para a página do fórum do projeto.

Versões anteriores

A documentação das versões anteriores podem ser encontradas em "verção n-1":link, "versão n-2":link .

Documentação do Bloco Y Versão m

Repete os itens do tópico anterior onde Y é uma parte do projeto e m é o número de versão.

Documentação do Bloco Z Versão l

Repete os itens do tópico anterior onde Z é uma parte do projeto e l é o número de versão


Contatos

  • Links externos e outros contatos.
  • Lista de e-mails: lista [arroba] doprojeto.com
  • Gerente do projeto: gerente [arroba] doprojeto.com
  • Outro contribuidor: outro [arroba] contribuidor.com

Licença

Indicar sob qual licença o projeto está. Destacar qual a licença da documentação e do produto.


Referências

1 Referência numerada de acordo com aparição no texto.

2 Flavio Depaoli, et al. 2015. Modelo de Documentação Padrão. [ONLINE] Disponível em: http://cta.if.ufrgs.br/projects/suporte-cta/wiki/Modelo_de_Documenta%C3%A7%C3%A3o_Padr%C3%A3o. [Acesso em 07 de Janeiro de 2015].


Este esboço de projeto é, por sua natureza, domínio público. Autores: Flávio Depaoli, Jan Luc Tavares, Renan Bohrer, Béuren Bechlin, Lucas Leal, Rafaela Wetternick.

RE: Discussão sobre o Modelo de Documentação Padrão - Added by Marina de Freitas about 3 years ago

Durante o Encontro do dia 09 de Maio de 2017 , conversamos sobre a proposta. Pensamos que é importante a existência do "Histórico do projeto",mas é opcional e se será documentado os momentos mais marcantes, ou os mínimos detalhes, fica a critério de cada um. Reforçamos o uso das tarefas como mecanismo de registro histórico, então falar sobre as Tarefas em Histórico do projeto é pertinente.

Os "Próximos passos" são bem importantes e, a exemplo da documentação da EMM, foi sugerido separar em "Metas" e "Aspirações". O primeiro são metas mais objetivas, enquanto o segundo são aspirações para um futuro mais distante, menos concretas que o anterior. Achei interessante que o nome é "Perspectivas do projeto", muito mais adequado.

Não foi comentado, mas acho pertinente falarmos de como deve ser a parte "Visão geral do projeto".

Não ficou claro qual o próximo passo, então fica no ar a proposta.

RE: Discussão sobre o Modelo de Documentação Padrão - Added by Marina de Freitas about 3 years ago

Estive pensando que outro ponto importante da documentação são os comentários e o cabeçalho de códigos. Seria importante termos isso bem descrito também, com exemplos e sugestões. O mesmo vale para desenhos de circuito. Vi que a forma como o Alisson e o Leonardo desenharam o circuito estava muito bonito e claro, isso poderia ser incluso da oficina de kicad (e no nosso manual) como dicas de documentação.

Nosso manual de documentação está ficando complexo e cheio de partes, penso que poderíamos faze-lo git book, um livro mesmo. Acho importante usarmos ferramentas mais comuns para documentar, o nosso site é bom e legal, mas é nosso.um conteúdo como uma manual de documentação, que queremos levar para muito lugares, é algo que pode vir a ter muitas contribuições externos ao CTA.

(1-5/5)