为Discourse撰写高效的文档

嘿,Simon! :blob_wave:

我本来想看看会发生什么,但嗯,我和你的看法一样,我尽量避免使用缩略语。

哈哈,是的……我不会在文档中使用这些词,以免暴露我的 :face_with_monocle:

绝对是:Example Domains

这就是我想来讨论的重点! :smiley:

我们对此进行了很多来回的讨论,很高兴看到它默认包含在风格指南中。

我认为这很重要,原因如下:编写文档需要尽可能地让我们的社区成员都能访问,包括(尤其是?)我们的 Discourse 团队成员。

Discourse 是一个社交、讨论软件。而有些文档实际上是一个持续的对话。如果我分享关于如何为我的社区成员入职的实践,我希望自己被呈现为该主题的“所有者”,这样我就可以回答问题并扩展该主题。

另一方面,如果客户询问我们从未解释过的功能,我希望能够使用风格指南并编写有用的、通用的文档,我认为成为主题所有者会阻碍发布。

另外,如果我们要在 Discourse 之外编写文档(集成或从代码注释生成等),拥有一个“文档用户”可能更容易作为实现细节。 :thinking:

我不认为本指南会阻止人们注入他们的声音和个性,并进行讨论。但如果它能帮助更多的人开始文档编写实践,而他们否则不会这样做(然后我们可以鼓励他们变得更具个性!),那就太好了! :smiley:

3 个赞