Melhorar README

[juuh42dias]

O readme atual não traz o contexto exato do projeto, podemos separar algumas especificações para a wiki como alternativa e deixar o readme com os passos básicos iniciais.

[juuh42dias]

Pode nos ajudar @contraexemplo?

[contraexemplo]

Observando o repositório pela primeira vez, a impressão que tenho é que o README não conversa de maneira efetiva com potenciais contribuidores. Eis o que espero de um bom README:

• Uma apresentação do projeto, uma descrição do que ele é, onde ele é aplicado, para quem ele foi pensado, com que mentalidade ele é desenvolvido. Algo que sumarize a visão do projeto.
• O que faz deste projeto algo interessante, talvez único? Por que alguém deveria usá-lo?
• Esse código está em produção em algum lugar, ou escrito pensando em algum uso específico, algum caso especial?
• Que tipo de contexto o contribuidor precisa ter para contribuir (funcionamento básico de uma unidade de saúde, histórias de usuário, conceitos básicos).
• (Isso aqui usa quase tudo que hoje consta no README) como começar a contribuir, e que tipo de conhecimento é mais necessário por aqui.

[juuh42dias]

E fazendo um adendo: “Como escrever boas documentações” by Lari Maza https://link.medium.com/GmKO66f1s6

[contraexemplo]

Também recomendo (em inglês) Writing a README do Mozilla Open Leaders (esse material fornece outras dicas de manutenção de um projeto aberto, aliás).

[contraexemplo]

A melhor dica que dou a qualquer pessoa que está pegando esse projeto para contribuir com certa frequência é, nos seus primeiros dias, escrever todas as dúvidas que você teve a respeito dele. Que tipo de materiais você buscou para se informar mais? Como você adquiriu conhecimento o suficiente para sentir segurança ao contribuir? Com a exceção de alguns casos raros, o caminho que você fez provavelmente será o caminho da maioria das pessoas interessadas em fazer uma contribuição. O seu objetivo é diminuir o tempo que elas empregam pesquisando coisas fáceis de responder e aumentar o tempo em que elas passam efetivamente pensando em soluções aos problemas propostos aqui.

[laurogripa]

Incluir links para download e instalação das principais dependências, como Docker e docker-compose.

[laurogripa]

Incluir seção sobre migrações do banco de dados

[dapx]

O readme do master possui uma seção Usando docker-compose, no master-covid não existe.

[dapx]

Outro ponto seria que o docker-compose está mapeando para a porta 4000 mas não é mencionado na doc, existe apenas a 3000. Acho que seria melhor manter o compose para mapear para a 3000 mesmo. Dificilmente o dev vai querer rodar o compose e local ao mesmo tempo, seria legal dar erro de porta em uso.

[dapx]

No readme a parte da cópia do config/database.yml.example, acho que poderia remover, pelo que vi já foi "commitado" o config/database.yml.

[dapx]

No readme o bin/rails db:setup não vai funcionar com o config/database.yml ou o example, pois o hostname nas configurações está como postgres, para funcionar no compose.

Acho que daria para manter o arquivo com localhost e definir uma environment variable no docker-compose para substituir pelo hostname postgres.

[bugarela]

A questão do config/database.yml foi resolvida aqui #92

[iago-silva]

Melhorias que eu puder perceber no README:

• Typo: "bundle exec rails serve"
• Diz para rodar bundle exec rubocop, mas o Rubocop não tá no gemfile
• Diz para rodar bundle exec rails test, mas o projeto tá usando Rspec
• Diz para rodar cp config/database.yml.example config/database.yml, mas o database.yml já tá versionado
• Diz para rodar rails db:setup, mas não funciona por causa do host: :postgres no database.yml