Documentação das Deciões

[pauloelr]

Proposta

Quando começamos a discutir as coisas aqui no Hexagon Project fizemos tudo com base nas issues, porém de uns tempos para cá andei percebendo que a medida que as issues foram sendo aprovadas e fechadas (nem tanto as de desenvolvimento que depois de prontas não tem mais muito o que acompanhar, mas principalmente as com conteúdo mais administrativo) acabam se perdendo no esquecimento.

MInha sugestão, começar a trabalhar com documentos em formato Markdown a serem armazenados nesse mesmo repositóio, basicamente no mesmo estilo das PSR's

As discussões continuariam acontecendo nas issues da mesma forma como estão hoje, porem tudo que fosse decidido seria documentado em um arquivo separado que ficaria para consulta e acompanhamento das decisões no futuro.

Caso alguma issue resultasse na alteração de uma decisão já tomada e documentada um PR poderia ser envaido para alterar o arquivo específico

Plano de Ações

Caso essa proposta seja aprovada acho que poderiamos começar criando documentos que descrevam os processos de aprovação das issues e os processo de documentação de cada uma delas (que forem definidos aqui).

Posteriormente fariamos uma revisão dos tópicos já abordados para documentação incluindo a separação de algumas informações que hoje estão presentes no README desse repositório para seus arquivos específicos

[williamespindola]

Acho que documentação pode ser a própria issue. Toma menos tempo e Time is Money!
O que deve ser feito é resumir o que aconteceu e adicionar ao primeiro texto da issue logo em baixo da proposta, ficaria mais rápido o processo de documentação.

[pauloelr]

Discordo do método de documentar na issue, hoje fazemos isso e as decisões acabam se perdendo em meio as issues que foram aprovadas e as que não resultaram em nada, além disso documentar as decisões em um arquivos específicos para cada um ajuda a centralizar o que já foi definido e facilita a busca das informações por parte daqueles que não estavam presentes no momento das discussões.

Mais do que pensar no tempo economizado agora estariamos pensando no tempo que economizariamos no futuro que seria muito maior, acredito que um pouco de esforço para criação desse documento compensário muito esforço que pode ser evitado futuramente.

[williamespindola]

É preciso diferenciar o que é de definição e o que tem início, meio e fim. Você tem razão se for algo que precisa ser definido mantido como uma Wiki (talvez ela sirva, tem histórico e versionamento).
As decisões se perdem nas issues por problemas de votação. O que foi definido e documentado virou PR como as tabelas de redes sociais. A issue do translation fest teve êxito, foi documentada no drive, mas poderia ter sido na issue como rolou a discussão até ir para o chat, após o evento acontecer se encerra a issue. Não obstante, virou definição vira PR ou pode ir para o site como um post em uma categoria doc.

[pauloelr]

Verdade, issues do tipo "organização de um novo evento" terminam no final da issue.
Mas decisões como por exemplo "O Processo de Votação" #27 ou "Objetivos dos Canais de Comunicação" #28 precisariam ser documentadas em algum lugar, algumas delas já foram incluídas no README do projeto, mas isso ainda é viavel pois poucas decisões desse tipo foram tomadas, a medida que esse número crescer ficaria enviavel manter tudo em um único arquivo.

Alem disso eu ainda acho que issue relativas a projetos específicos, como por exemplo alterações no blog, deveriam ficar no repositório do projeto em questão (no caso o https://github.com/PHPSP/phpsp-blog-theme) e esse repositório deveria ficar para decisões mais administrativas.

E ai poderiamos usar as tags para separar as issues por tipo e definir como cada tipo deve ser documentado, mas isso também depende do andamento da issue #27 que liberaria o uso das tags para esse tipo de marcação.

Por isso que eu deixei para abrir essas issues todas juntas, pois uma acaba influenciando na outra.

E mais uma tentativa de produzir um esforço conjunto para definir os procedimentos para o processo de tomada de decisões e suas repercussões futuras, acho que uma definição disso tudo em conjunto pode sim ser trabalhoso inicialmente mas pode resultar em um ambiente muito mais gerenciável e convidativo para a participação de novas pessoas.

[pauloelr]

Esqueci ainda de um ponto, não acho que o blog seja o canal adequado para divulgação desse tipo de informação, acho ele mais adequado para divulgação de conteúdo técnico mesmo e como porta de entrada para que novos participantes possam encontrar os canais adequados para cada coisa.

[gabrielrcouto]

Issue de algo que gera uma ação -> Vai para o README, com data de início e fim dessa ação e equipe responsável. Coisas sem prazo nunca são feitas.

Issue de algo que não gera uma ação -> Continua na issue, ela mesma já é uma documentação.

[pauloelr]

Defina issue que gera ação e issue que não gera ação, não entendi direito o que você quis dizer com cada um desses tipos,

Uma issue evento seria uma issue que gera ação? Uma decisão sobre o sistema de votação e uma issue que não gera uma ação?

Se for isso sou contra os dois casos, README superlota e pra mim é espaço pra explicar para que serve esse repositório e nada mais

Issue se perde no meio das outras, hoje são menos de trinta e muitas vezes tenho que abrir várias para achar alguma informação sobre algo que foi decidido.

Minha sugestão continua sendo
Issue para discutir
Arquivo em Markdown para documentar
README para explicar o repositório

[gabrielrcouto]

Issue que gera ação -> São aquelas que se concluem em tarefas, como organizar um evento, arrumar um bug ou criar um plano.

Issue que não gera ação -> São aquelas que definem regras do grupo, apenas burocráticas.

Uma issue com a proposta de um evento gera tarefas, ou seja, precisam ser colocados prazos e responsáveis. Agora, uma issue que é sobre o grupo permitir ou não novos patrocinadores, é apenas uma votação, não gera diretamente tarefas. Isso está diretamente ligado a issue #27 que você postou hoje.

[pauloelr]

Era isso mesmo que eu estava pensando

Concordo que issues que geram ação tem. Início meio e fim nelas mesmos, mas ainda acho que correções de bugs devem ficar nos repositórios específicos de cada projeto.

Só com relação às que não geram ação acho que deveriam ganhar uma casa mais permanente que a issue, pois a medida que o número de issues vai crescendo elas vão se perdendo no meio das outras e mesmo muito do que é discutido na issue acaba sendo descartado.

A idéia seria documentar somente o que for aceito num documento mais permanente e mais acessível, minha sugestão de utilizar arquivos Markdown no repositório funciona muito bem com o FIG e acho que já está muito claro o quanto eles conseguiram avançar tendo como base essa metodologia

[pauloelr]

Esqueci de falar ainda que sim, as três issues que eu criei juntas tem bastante pontos de influência entre elas. Por isso que deixei pra criar tudo junto.