Introdução

Livro de Receitas vs. Guia

Como o livro de receitas (cookbook) é diferente do guia? Por que ele é necessário?

Com todas essas diferenças, observe que o livro de receitas ainda não é um manual passo-a-passo. Para a maioria de seu conteúdo, espera-se que você tenha uma compreensão básica de conceitos como HTML, CSS, JavaScript, npm/yarn, etc.

Fazendo Contribuições

O Que Procuramos?

O livro de receitas fornece aos desenvolvedores desde exemplos comuns a casos de uso interessantes. Também pode explicar progressivamente, em detalhes, coisas complexas. Nosso objetivo é ir além de um simples exemplo introdutório e demonstrar conceitos que são amplamente aplicáveis, bem como algumas ressalvas à abordagem utilizada.

Se você está interessado em contribuir na versão em português, siga as instruções existentes no README assim como para o restante da documentação. Se você está interessado em contribuir diretamente em inglês, por favor, inicie a colaboração preenchendo uma issue no respositório principal com a tag cookbook idea e uma explicação (obviamente, em inglês), para que possamos te ajudar a realizar com êxito o pull request. Depois que sua ideia for aprovada, por favor, siga o modelo abaixo tanto quanto possível. Algumas seções são necessárias e algumas são opcionais. Sugerimos veementemente que siga a ordem numérica, apesar de não ser obrigatório.

Os exemplos devem geralmente:

  • Resolver um problema comum e específico
  • Começar com o exemplo mais simples possível
  • Introduzir complexidades, uma de cada vez
  • Ter links para outros documentos, em vez de reexplicar conceitos
  • Descrever o problema, em vez de assumir a familiaridade
  • Explicar o processo, em vez de explicar só o resultado final
  • Explicar prós e contras de sua estratégia, inclusive quando ela não é apropriada
  • Mencionar soluções alternativas, se relevantes, mas sem se aprofundar

Solicitamos que você siga o modelo abaixo. Entendemos, entretanto, que há momentos que você pode necessariamente precisar se desviar para alcançar objetividade e clareza. De qualquer modo, todos os exemplos devem, em algum ponto, discutir a escolha feita usando esse padrão, de preferência na forma da seção de padrões alternativos.

Exemplo Base

obrigatório

  1. Articular o problema em uma ou duas sentenças.
  2. Explicar a solução mais simples possível em uma ou duas sentenças.
  3. Mostrar uma pequena amostra do código.
  4. Explicar qual o objetivo disso em uma sentença.

Detalhes da Importância

obrigatório

  1. Abordar dúvidas comuns que alguém possa ter enquanto visualiza o exemplo. (blockquote é ótimo para isso)
  2. Mostrar exemplos de erros comuns e como eles podem ser evitados.
  3. Mostrar, de forma simplificada, exemplos de códigos bons e ruins.
  4. Discutir o porquê do padrão utilizado ser o ideal. Referências são incentivadas.

Exemplo do Mundo Real

obrigatório

Demonstrar que o código pode ser um caso de uso comum ou interessante, através de:

  1. Alguns exemplos sucintos de configuração, ou
  2. Incorporando um exemplo no codepen/jsfiddle

Se você escolher fazer o último, ainda assim deve explicar o que ele faz.

Notas Adicionais

opcional

É extremamente útil escrever um pouco sobre este padrão. Por exemplo, onde ele se aplica, por que ele funciona bem e percorrer um pouco do código ou fornecer aos leitores um pouco mais de material de leitura.

Quando Evitar o Padrão

opcional

Esta seção não é obrigatória, mas é muito recomendada. Não fará sentido escrevê-la para algo muito simples, como alternar classes com base na mudança de estado. Mas, para padrões mais avançados, como mixins, é fundamental. A resposta para a maioria das perguntas sobre desenvolvimento é “Depende!”. Aqui, vamos aplicar um olhar honesto sobre quando o padrão é útil e quando deve ser evitado, ou quando algo faz mais sentido.

Padrões Alternativos

obrigatório

Esta seção é necessária quando você usa a seção acima. É importante explorar outros métodos. Então, se as pessoas acharem que algo não deve ser usado em certas situações, elas não ficarão na dúvida. Ao fazer isso, considere que a Web é um grande local em que muitas pessoas têm diferentes tipos de código, e estão resolvendo problemas diferentes. A aplicação é grande ou pequena? Está integrando o Vue em um projeto existente ou está sendo construído do zero? Seus usuários estão apenas tentando alcançar um objetivo ou vários? Existem muitos dados assíncronos? Todas essas preocupações irão afetar diferentes implementações. Um bom exemplo do livro de receitas dá aos desenvolvedores o contexto da solução.

Obrigado

É preciso tempo para contribuir com a documentação. Então, se você usar o seu tempo para enviar um pull request para esta seção de nossos documentos, faça isso com toda nossa gratidão.