Escrevendo documentação eficaz para Discourse

Até termos uma forma nativa de lidar com documentos localizados, acho que prefixar o título com bandeiras é a maneira mais prática de fazer isso, e uma exceção razoável a esta diretriz.

Acho que esse tipo de coisa tem opiniões e preferências diferentes de qualquer maneira, mas para este guia de estilo, estamos seguindo as normas aceitas pela indústria. Mais uma vez, as diretrizes do Google e da Microsoft concordam que é melhor usar contrações comuns.

Dito isso, li algumas postagens sugerindo que o uso de contrações negativas (como “can’t”) pode dificultar a compreensão para falantes não nativos de inglês. Vamos investigar isso um pouco mais e, se necessário, atualizar o guia de estilo de acordo.

Removi esse exemplo! :smile:

Sim - isso é muito comum (não apenas no Discourse), mas concordo que não está totalmente correto. Usar aspas seria melhor, então acho que vou deixar isso explícito no guia de estilo.

Esse é um ótimo ponto - vou adicionar isso ao guia de estilo!

Obrigado por este feedback! @maiki fez alguns bons pontos acima, e concordo com o que ele diz lá. Para acrescentar a isso, direi que uma das razões pelas quais mudamos a autoria da documentação oficial para @Discourse é para dar a eles um maior senso de autoridade para os leitores, especialmente para as pessoas que estão acessando a documentação pela primeira vez. Este é também o ímpeto por trás de todo o guia de estilo em primeiro lugar.

Qualquer pessoa que escreva documentação pode definitivamente injetar sua personalidade em sua escrita, e a discussão sobre tópicos individuais de documentação não vai a lugar nenhum, então esse é sempre um bom lugar para tornar as coisas mais pessoais também.

Todo esse feedback é muito apreciado :slight_smile:

2 curtidas