やあ、サイモン! ![]()
この件については様子を見ようと思っていましたが、私も同じように、短縮形を避けるようにしています。
Discourse:
moreover, although, hence, therefore のような接続詞を使用する
moreover?
ハハ、ええ…ドキュメントであのような言葉を一切使わないようにします。さもないと、私の
が露呈してしまいます。
Discourseサイトを参照するためのプレースホルダー名を一貫して使用することは、検討する価値があるかもしれません。たとえば
discourse.example.comのようなものでしょうか? ここには、Discourseサイトをsitename.comと参照しているドキュメントがいくつかあります。それは私を非常に混乱させました。
確かに:Example Domains
ドキュメントトピックが私に割り当てられなくなったことをどれほど感謝しているかに関わらず、チームのすべてのドキュメントトピックの作成者としてDiscourseを使用することは、少し冷たく感じられます。
私にとって執筆が再び楽しくなったのは、書いているものに自分自身を少しでも反映させる方法を探すというアドバイスでした。それは、あなたの口調、あなたの趣味、何でも…ここでは推奨されていることとは正反対のことです。
これが私が議論するためにここに来たポイントです! ![]()
この件については、多くの議論がありましたが、これがスタイルガイドにデフォルトで含まれているのを見て嬉しかったです。
これが重要だと考える理由は次のとおりです。ドキュメントの作成は、コミュニティの可能な限り多くのメンバー、特にDiscourseチームのメンバーにとってアクセスしやすいものである必要があります。
Discourseはソーシャルなディスカッションソフトウェアです。そして、一部のドキュメントは実際には継続的な会話です。コミュニティのメンバーをオンボーディングする方法の実践を共有する場合、そのトピックの「所有者」として提示されたいので、質問に答えたり、主題を拡張したりできます。
一方で、顧客が私たちがまだ説明できていない機能について尋ねてきた場合、スタイルガイドを使用して有用で一般的なドキュメントを作成できることを望みます。これは、トピックの所有者であることが公開により大きな慣性を与えると私が感じていることです。
また、Discourse以外でドキュメントを作成する場合(統合やコードコメントからの生成など)、ドキュメントユーザーがいる方が実装の詳細としてはおそらく簡単です。 ![]()
このガイドが、人々が自分の声や個性を注入することを止めることはないと思います。そして議論をホストすることも。しかし、そうでなければドキュメントを作成しないであろうより多くの人々がドキュメント作成の実践に参加するのに役立つことを願っています(そしてその後、彼らに個人的になるように促すことができます!) ![]()