ドキュメントの編集

この記事では、WSOFTDocsの記事を直接編集する方法を説明します。

taiseiue | 2022-11-01
  • 共有
  •  記事の編集

WSOFTDocsの記事では、ドキュメントの編集を使用することで、軽微な誤字脱字やその他の問題を簡単に報告および修正できます。

概要

どれだけ努力を重ねても、公開されているドキュメントには必ず誤植や表現上の細かいミスが含まれてしまいます。そのようなミスに気づかれた場合は、リポジトリでIssueを作成して報告していただくこともできますが、可能であれば直接編集してPull Requestを作成することで、より迅速かつ簡単に修正できます。

ドキュメントを編集するには、以下のいずれかの方法を使用できます。

  1. ブラウザを使って編集する
  2. Gitと好きなエディターを使ってローカルで編集する

簡単な修正を行う場合はブラウザを使って編集するほうが早くて簡単ですが、複数の記事を変更する場合や新たに画像をアップロードする場合、使い慣れたエディターで編集したい場合はローカルで編集することをオススメします。

ブラウザを使って編集する方法

  1. ドキュメントの編集を行うには、GitHubのアカウントが必要です。すでにアカウントをお持ちの場合は、GitHubにサインインしていることを確認してください。GitHubアカウントをお持ちでない場合は、GitHubのサイトから登録できます。
  2. 編集するドキュメントのページを開きます。ドキュメントの編集が利用可能な場合、以下の画像のような「編集」ボタン(鉛筆アイコン)が表示されます。このボタンをクリックすると、GitHub上のソースファイルに移動します。「編集」ボタン
  3. 鉛筆アイコンをクリックして記事を編集します。鉛筆アイコンが灰色に表示されている場合は、自分のGitHubアカウントでログインするか、新しいアカウントを作成する必要があります。鉛筆アイコン
  4. Webエディターでファイルを編集します。
  5. 編集が完了したら、ページの下部までスクロールします。「変更の提案」領域に変更の簡単な概要（"誤字の修正"、"表現の改善"など）と、必要に応じて説明を入力します。タイトルはコミットメッセージの最初の行になります。入力できたら、「変更の提案」をクリックして変更をコミットします。変更の提案
  6. 変更の提案が済んだため、その変更をリポジトリに"Pull"するよう、そのリポジトリの所有者に依頼し、コミットする必要があります。これを完了するには、"PullRequest"と呼ばれる作業を実行します。「Propose changes」をクリックしてPullRequestを作成します。GitHubをはじめてお使いの場合、詳細についてはPull requestについてを参照してください。
  7. これで完了です。WSOFTのメンバーが、Pull Requestをレビューし、承認されればそれをマージし、サイトに反映します。編集内容に関する質問などをお伺いすることがあるため、GitHubの通知を受け取れるようにしておいてください。

ローカルで編集する方法

編集の準備

以下の操作は、初回のみ必要です。

  1. ローカルでドキュメントの編集を行うには、Gitがインストールされているコンピューターが必要です。すでにGitがインストールされている場合は、適切にユーザー名と電子メールアドレスが設定されていることを確認してください。Gitがインストールされていない場合は、Gitのサイトまたはパッケージマネージャーからインストールできます。
  2. 作業ディレクトリにWSOFT Docsのリポジトリをクローンし、ブランチを作成します。このとき、ブランチ名には他と被らないように名前や目的などをいれてください。(たとえば、taiseiue-editブランチなど。)実際にクローンしてブランチを作成するには、以下のコマンドを実行します。<ブランチ名>は、適時変更してください。
$ git clone https://github.com/WSOFT-Project/docs.git
$ git branch -b <ブランチ名>

編集開始

以下の操作は、編集時に毎回行う必要があります。

  1. 作業ディレクトリに移動して、git pullコマンドを実行します。
  2. 任意のエディターで、作業ディレクトリ内のドキュメントを編集します。
  3. 編集が完了したら、編集内容をアップロードします。作業ディレクトリで以下のコマンドを実行してください。<コミットメッセージ>には、作業内容の概要を入力してください。
$ git add .
$ git commit -m "<コミットメッセージ>"
$ git push

Pull Requestの作成

Pull Requests画面

Comparing changes画面

Open a pull request画面

  1. WSOFTDocsのPull Requestページにアクセスし、「New pull request」をクリックします。
  2. Comparing changesに移動したら、compareを自分のブランチに、baseをmasterに設定し、編集内容を確認して「Create pull request」をクリックします。
  3. Open a pull requestに移動したら、編集内容のタイトルと説明を入力し、Create pull requestをクリックします。
  4. これでPull Requestの作成は完了です。WSOFTのメンバーが、Pull Requestをレビューし、承認されればそれをマージし、サイトに反映します。編集内容に関する質問などをお伺いすることがあるため、GitHubの通知を受け取れるようにしておいてください。