Pecan: Esboço da Documentação

@robkooper e @ashiklom tentaram combinar suas duas idéias de um esboço. Seria bom receber seu feedback para @KristinaRiemer e @bailsofhay . Vamos começar a implementar isso em breve para que possamos mover as páginas para onde queremos antes do final do mês.

Eu acho que isso parece muito bom. Isso é apenas reorganizar o material existente, sem adicionar nada?

Quando você está fazendo isso, o capítulo 41 deve ir antes de 40.

@KristinaRiemer Sim, vou apenas mudar as coisas. Nesse ínterim, podemos identificar coisas que estão faltando e criar problemas. Observe que isso é rotulado como um problema "épico", portanto, esses outros problemas podem ser vinculados a este problema para que possamos nos manter organizados.

Eu estava apenas procurando na documentação por algum jargão para usar em uma rápida escrita sobre o que eu faço. Percebi que o doc não tem a melhor explicação de por que alguém iria querer usar noz-pecã (especificamente, está faltando qualquer explicação para a análise de incerteza). Faria sentido colocar na seção "Visão geral do projeto" do documento disponível atual, sem saber onde adicionar para o reorganizado em que estamos trabalhando.

Link de @infotroph sobre a documentação: https://www.divio.com/blog/documentation/

Link de @infotroph sobre a documentação: https://www.divio.com/blog/documentation/

Mais contexto: esta peça apresenta um caso fortemente argumentado de que existem quatro tipos distintos de documentação de software, e que todos os projetos bem documentados precisam ter todos os quatro como seções explicitamente separadas:

• tutoriais , para ensinar aos iniciantes o que sua ferramenta faz usando exemplos passo a passo que garantem funcionar exatamente como descrito todas as vezes
• como fazer , a seção do livro de receitas onde os usuários podem ir para responder a perguntas do formulário "Como faço para ...?", contendo apenas os detalhes de que precisam para uma determinada pergunta
• referência , para obter os detalhes da página do manual sobre como chamar as coisas, quais protocolos falam e quais valores retornam
• discussão , em que você explica por que as coisas funcionam do jeito que funcionam, fornece informações básicas, aconselha sobre práticas boas e más e fornece um contexto que não se encaixa nas outras seções.

Este problema está desatualizado porque esteve aberto 365 dias sem atividades.

A longo prazo, acho que o conceito de tutorial / como fazer / referência é sólido e que ainda poderíamos esclarecer a documentação aplicando-o de maneira mais uniforme. Mas a reorganização discutida originalmente aqui foi implementada de maneira completa o suficiente para que encerrarei este problema e incentivarei novos threads para qualquer limpeza posterior.