ドキュメントへの貢献

Cucumberのドキュメントはオープンソースであり、誰でも貢献できます。実際、私たちはあなたの助けを本当に感謝しています！

各ページには、そのページのコンテンツを編集するためのリンクが用意されています。また、Githubのdocs.cucumber.ioプロジェクトに変更を加えることもできます。

プロセス

初めて**貢献**する方は、プルリクエストを送信する必要があります。

最初のプルリクエストが承認されると、あなたは**コミッター**に昇格し、GitHubリポジトリへの書き込みアクセス権が付与されます。**コミッター**であっても、プルリクエストを使用する必要があります。

各プルリクエストは、単一のトピックのみを変更/追加する必要があります。無関係なドキュメントの変更を同じプルリクエストにまとめてしないでください。複数のトピックを変更または追加する場合は、トピックごとにプルリクエストを開いてください。

タイトルには、どのドキュメントを変更/作成しているのか、そしてその理由を説明する必要があります。たとえば、`[docs] Add tags.md`または`[docs] Modify tags.md to explain boolean expressions`のようにします。

より一般的な貢献プロセスは、Cucumberコミュニティ貢献ガイドに記載されています。

ドキュメントについて議論する

あなたの書いたものに対するフィードバックを得るのは素晴らしいことです。まずは小さな変更から始め、プルリクエストで他の貢献者からのフィードバックを待ちましょう。

質問や議論をするために、Cucumber Discordに参加することができます。

何に貢献するか

貢献を始めるための良い方法は、Cucumber DiscordまたはGitHubディスカッションボードで質問に答えることです。ドキュメントに現在欠けている質問への回答を追加することができます。

また、FAQページに質問を追加し、ドキュメントの関連部分へのリンクを貼ることもできます。

GitHubのdocs.cucumber.ioプロジェクトで、`Good first issue`または`Help wanted`とマークされたissueを探すこともできます。これらのissueについて質問がある場合は、issue自体にコメントを追加するか、Discordでご連絡ください。

一般的な記述スタイル

一般的に、ドキュメントは簡潔で要領を得たものにする必要があります。

完璧とは、 더 이상 추가할 것이 없을 때가 아니라, 더 이상 뺄 것이 없을 때 이루어진다 - アントワーヌ・ド・サン＝テグジュペリ

いくつかのガイドライン

  • すべてのページは、情報提供/動機付けの段落で始まる必要があります。
  • 段落は、読みやすい程度に短く、しかしアイデアを展開できる程度に長くする必要があります。
  • すべてのページは`h1`見出しで始まる必要があります。セクションは`h2`を使用し、サブセクションは`h3`を使用します。
  • 長い行は改行します。80列目あたりに新しい行を挿入します。これは、レビューコメントが行にのみ追加できるため重要です。
  • 現在形で記述します。
  • 中立的な言葉遣いを心がけつつ、少し面白みのある文章にしましょう（これは難しいです！）。
  • できるだけプラットフォームに依存しない方法で記述します。Cucumberは複数の言語で実装されており、ドキュメントは特定のプラットフォームを想定すべきではありません。
  • すべてのコード例（Gherkinを除く）と、1つ以上の特定の言語に関連する段落には、コードブロックを使用します。
  • 1つ以上の特定の言語にのみ関連するテキストには、言語ブロックを使用します。
  • 必要に応じて、多言語ページとしてマークします。
  • すべてのドキュメントはイギリス英語を使用する必要があります。アメリカ英語での貢献は問題ありません。編集者が翻訳を行います。
  • 外部リンクへのリンクは控えめに使用してください。
  • 著作権で保護された素材（画像、テキストなど）を使用しないでください。
  • イラストは素晴らしいですが、ローファイの図面を使用してください。Cucumberの設計チームが、Cucumberのブランドガイドラインに従ってイラストを再作成します。
  • 貢献内容を現在のドキュメントと*一貫性*を持たせるようにしてください。たとえば、
    • 一貫した言葉遣いとフォーマットを使用する
    • キーワードをバッククォートで囲みます。この場合、キーワードは大文字で書くことができます。例：`ステップ定義`
    • 文中で概念を参照する場合は小文字を使用します。例：「ステップ定義」ではなく「ステップ定義」

チュートリアルの記述スタイル

  • 読者はトピックに関する知識がほとんどない、あるいはまったくないと仮定します。
  • 会話調のスタイルを使用します。
  • チュートリアルの各ステップが明確に記述されていることを確認します。
  • 必要に応じて、各ステップの結果がどうなるかを説明します。

ツールチェーン

ドキュメントはMarkdownで記述されています。

ドキュメントはGithubのdocs.cucumber.ioプロジェクトに保存されています。

メニュー構造

ページは独自のセクションに表示されます。これは、ファイルが配置されているディレクトリです。セクション内のページはデフォルトでアルファベット順に並べられますが、`weight`を指定することでオーバーライドできます。

ページ構造

  • YAMLフロントマター（タイトルと概要を含む）
    • コードまたは言語固有のテキストを含むページは、多言語ページとしてマークする必要があります。
    • メニュー内の（相対的な）順序を指定するために`weight`を指定します（#menu-structureを参照）。
  • 導入段落
  • 段落

YAMLフロントマターからのページのタイトルは、ページの上部に`<h1>`見出しとしてレンダリングされます。本文は見出しではなく、段落で始めます。見出しで始めると、ページの上部に`h1`の直後に別の見出しが続き、見栄えが悪くなります。

多言語ページ

ページには、特定のプログラミング言語のテキストまたはソースコードを条件付きで表示する、同じコンテンツのバリエーションを含めることができます。

ページがフロントマターで以下を指定している場合、言語選択が表示されます。

 polyglot:
 - java
 - javascript
 - ruby
 - kotlin
 - scala
 - dotnet

現在、以下の言語がサポートされています。

  • Java
  • JavaScript
  • Ruby
  • Kotlin（オプション）
  • Scala（オプション）

  • .Net（オプション、一部のページのみ）

  • 可能な限り、Java、JavaScript、Rubyの情報を含めることをお勧めします。

    • 1つのプログラミング言語しか知らない場合は、その言語の例を追加してください。他の言語については、他の誰かがギャップを埋めてくれるでしょう！
    • 他の言語については、Discordのその言語のヘルプチャンネル、またはGitHubのプルリクエスト/issueで yardım を求めることができます。

言語固有のソースコードと段落

段落およびフェンス付きコードブロックを`{{% block %}}`ショートコードで囲みます。

{{% block "ruby" %}}
Put this in your `hello.rb`:

```ruby
puts "hello"
```
{{% /block %}}

{{% block "javascript" %}}
Put this in your `hello.js`:

```javascript
console.log("hello")
```
{{% /block %}}

{{% block "java" %}}
Put this in your `Hello.java`:
```java
System.out.println("hello")
```

{{%/* block "kotlin" %}}
Put this in your `Hello.kt`:
```kotlin
println("hello")
```
{{% /block %}}

{{% block "scala" %}}
Put this in your `Hello.scala`:
```scala
println("hello")
```
{{% /block %}}

言語ブロック*内*に見出しを使用することはできません！特定の言語のコンテンツを含むページを作成する場合は、別のページにする必要があるかもしれません。または、言語ごとに見出しを使用することもできます。

言語固有のテキストフラグメント

特定のプログラミング言語に対してのみ表示する必要があるテキストフラグメントを`{{% text %}}`ショートコードで囲みます。

The preferred build tool is
{{% text "ruby" %}}Rake{{% /text %}}
{{% text "javascript" %}}Yarn{{% /text %}}
{{% text "java,kotlin,scala" %}}Maven{{% /text %}}.

複数のプログラミング言語で有効な段落またはテキスト

複数の言語で有効な段落またはテキストにショートコードを使用することもできます。個々の言語ごとに繰り返す必要はありません。そのためには、関連する言語をカンマ（`,`）で区切ってリストします。

{{% text "java,kotlin,scala" %}}Maven{{% /text %}}

追加のショートコード

追加のショートコードはlayouts/shortcodesで定義されています。

メソッド vs 関数

stepdef の本文用に特定のショートコードが作成されました。

{{% stepdef-body %}}

このショートコードを使用すると、テキスト内でプログラミング言語に応じてmethodまたはfunctionという単語に置き換えられます。

式パラメータ

式パラメータ用に特定のショートコードが作成されました。

{{% expression-parameter %}}

このショートコードを使用すると、テキスト内でプログラミング言語に応じてキャプチャグループまたは出力パラメータという単語に置き換えられます。

ローカルでの作業

ローカルで作業してプロジェクトをビルドする方法については、README.mdをご覧ください。

このドキュメントの改善にご協力ください。このページを編集する