Escrevendo documentação eficaz para Discourse

Olá Simon! :blob_wave:

Eu ia ver como isso se desenrolaria, mas sim, eu sou o mesmo, eu tento evitar contrações.

Hahaha, sim… Não vou usar nenhuma dessas palavras na documentação, para não revelar meu :face_with_monocle:.

Com certeza: Example Domains

Este é o ponto que vim discutir! :smiley:

Tivemos muita discussão sobre isso, e fiquei feliz em ver isso incluído no guia de estilo por padrão.

Aqui está o porquê eu acho que é importante: produzir documentação precisa ser acessível para o maior número possível de membros da nossa comunidade, incluindo (especialmente?) nossos membros da equipe do Discourse.

Discourse é um software social de discussão. E alguma documentação é realmente uma conversa contínua. Se estou compartilhando uma prática sobre como eu integro membros à minha comunidade, eu gostaria de ser apresentado como o “proprietário” desse tópico, para que eu possa responder a perguntas e expandir o assunto.

Por outro lado, se um cliente pergunta sobre um recurso que nunca explicamos, eu gostaria de poder usar o guia de estilo e produzir documentação útil e geral, o que sinto que ser o proprietário do tópico apresenta mais inércia para a publicação.

Além disso, se produzirmos documentação fora do Discourse (uma integração ou produção a partir de comentários de código ou o que for), ter um “usuário de documentação” é provavelmente mais fácil como um detalhe de implementação. :thinking:

Não acho que este guia impedirá as pessoas de injetar sua voz e personalidade, e hospedar a discussão. Mas seria ótimo se ajudasse mais pessoas a entrar na prática de documentar, que de outra forma não o fariam (e então poderemos incentivá-las a serem mais pessoais!) :smiley:

3 curtidas