スタイルガイド

入門

ライティングを始める前に理解しておくべきことがあります:

1. Determine purpose and use

   あなたの記事の目的を定めることは、あなたの執筆プロセスの最初のステップであるべきです。読者が読み終わったときに何を知って欲しいかを明確にすることです。目的を定義することは、各ステップを執筆する上であなたの助けになるでしょう。

2. Identify the audience and their need

   Keep in mind that the documentation will be mostly read by curious or contributing developers and system integrators, who we should assume to have at least an elementary level of technical knowledge. Determine what information, and how much detail, the readers need to achieve the purpose of your article.

3. Organize the information

   読者に必要な情報が決まったら、情報を論理的に整理して最良の流れと理解を得ます。

これで書き始める準備が整いました！プロジェクトをダウンロードしてドキュメントを提出する方法を学ぶために page を確認してください。

ツール

Sphinx: Sphinx is the documentation generator we use to facilitate writing documentation. Its features (extensive cross-references, hierarchical structure, automatic indices, etc) and range of languages make it a useful tool for our purposes.

reStructuredText: Sphinx uses reStructuredText as its markup syntax. reStructuredText is a straightforward yet powerful system that is a major strength of using Sphinx. You can refer to the reStructuredText cheat-sheet for the basics.

GitHub: GitHub is the hosting service we use for our documentation. To commit your contributions, you will need to be familiar with the platform. Beginners can start learning by reading this introduction to Git.

Transifex: Transifex is the collaborative localization platform we use to translate our documentation to various languages. Follow our guide to start contributing to the translations.

記述パターン

While it is unreasonable to expect all of the many writers on the technical writing team to have an identical writing style, we can attempt to have a consistent voice that resonates with the readers by maintaining a similar writing pattern. Keep in mind these basic rules as you write.