嘿,Simon! ![]()
我本来想看看会发生什么,但嗯,我和你的看法一样,我尽量避免使用缩略语。
Discourse:
使用过渡词,例如 moreover, although, hence, 和 therefore
moreover?
哈哈,是的……我不会在文档中使用这些词,以免暴露我的
。
使用一致的占位符名称来引用 Discourse 站点可能值得一试。也许是
discourse.example.com?这里有一些文档将 Discourse 站点称为sitename.com。这让我非常困惑。
绝对是:Example Domains
尽管我很感激不再有大量文档主题归属于我,但将 Discourse 作为所有团队文档主题的作者感觉有点冷淡。
对我来说,重新找回写作乐趣的是那个建议:寻找方法将自己的一部分融入你所写的任何内容中。它可以是任何东西,你的语气、你的爱好,随便什么……这与这里推荐的做法有点相反。
这就是我想来讨论的重点! ![]()
我们对此进行了很多来回的讨论,很高兴看到它默认包含在风格指南中。
我认为这很重要,原因如下:编写文档需要尽可能地让我们的社区成员都能访问,包括(尤其是?)我们的 Discourse 团队成员。
Discourse 是一个社交、讨论软件。而有些文档实际上是一个持续的对话。如果我分享关于如何为我的社区成员入职的实践,我希望自己被呈现为该主题的“所有者”,这样我就可以回答问题并扩展该主题。
另一方面,如果客户询问我们从未解释过的功能,我希望能够使用风格指南并编写有用的、通用的文档,我认为成为主题所有者会阻碍发布。
另外,如果我们要在 Discourse 之外编写文档(集成或从代码注释生成等),拥有一个“文档用户”可能更容易作为实现细节。 ![]()
我不认为本指南会阻止人们注入他们的声音和个性,并进行讨论。但如果它能帮助更多的人开始文档编写实践,而他们否则不会这样做(然后我们可以鼓励他们变得更具个性!),那就太好了! ![]()