diff --git a/_posts/2021-12-04-meta-how-to-edit-wiki.md b/_posts/2021-12-04-meta-how-to-edit-wiki.md index fe8dd1f..0999f67 100644 --- a/_posts/2021-12-04-meta-how-to-edit-wiki.md +++ b/_posts/2021-12-04-meta-how-to-edit-wiki.md @@ -11,20 +11,20 @@ excerpt: "" # 準備 -GitHubにログインした状態でWikiをcloneします。 +GitHub にログインした状態で Wiki を clone します。 ```sh $ git clone git@github.com:brain-hackers/wiki.brainux.org.git ``` -2022/1/8現在、Ubuntu 20.04.3 LTSでは以下のコマンドでRuby 2.7がインストールされます。お使いのディストリビューション標準のパッケージマネージャーでRuby 2.7系がインストールできない場合、rbenvを使うなどして適宜Ruby 2.7系の最新バージョンをインストールしてください。 +2022/1/8 現在、Ubuntu 20.04.3 LTSでは以下のコマンドで Ruby 2.7がインストールされます。お使いのディストリビューション標準のパッケージマネージャーで Ruby 2.7 系がインストールできない場合、rbenv を使うなどして適宜 Ruby 2.7 系の最新バージョンをインストールしてください。 ```sh $ sudo apt install ruby-full ``` -Rubyがインストールできたら、以下のようにしてRuby 2.7が実行されることを確認します。 +Ruby がインストールできたら、以下のようにして Ruby 2.7 が実行されることを確認します。 ```sh $ ruby -v @@ -32,10 +32,12 @@ ruby 2.7.0p0 (2019-12-25 revision 647ee6f091) [x86_64-linux-gnu] ``` 次に手元でのビルドに必要な依存関係をインストールします。 +インストールには Bundler を用います。Bundler は gem を使ってインストールしてください。 ```sh $ cd wiki.brainux.org +$ sudo gem install bundler $ bundle install ``` @@ -58,14 +60,14 @@ Configuration file: /Users/takumi/dev/brain/wiki.brainux.org/_config.yml Server running... press ctrl-c to stop. ```` -次に、Textlintとmarkdownlintを使うためにNode.jsとパッケージをインストールします。 +次に、Textlint と markdownlint を使うために Node.js とパッケージをインストールします。 ```sh $ cd wiki.brainux.org $ npm install ``` -Node.jsのインストール方法とバージョンは動けば何でも良いです。まずはパッケージマネージャーでインストールしたNode.jsを使ってみて、うまく行かなければnodeenv（nodenvではない！）を使う以下の方法を試してください。nodeenvでインストールした場合は、毎回envをactivateするのを忘れないでください。 +Node.js のインストール方法とバージョンは動けば何でも良いです。まずはパッケージマネージャーでインストールした Node.js を使ってみて、うまく行かなければ nodeenv（nodenvではない！）を使う以下の方法を試してください。nodeenv でインストールした場合は、毎回 env を activate するのを忘れないでください。 ```sh $ pip install nodeenv @@ -74,14 +76,14 @@ $ source ./env/bin/activate (env) $ npm install ``` -Textlintを動かして、正常にlintされるか試します。`npm run textlint-fix`で発動する自動修正は、誤検知も意図せず修正してしまう可能性があるため事前によくチェックしてから実行してください。 +Textlint を動かして、正常に lint されるか試します。`npm run textlint-fix` で発動する自動修正は、誤検知も意図せず修正してしまう可能性があるため事前によくチェックしてから実行してください。 ```sh $ npm run textlint $ npm run textlint-fix # お好みで ``` -markdownlintを動かして、正常にlintされるか試します。 +markdownlint を動かして、正常に lint されるか試します。 ```sh $ npm run mdlint @@ -98,32 +100,33 @@ $ npm run mdlint - `_posts` ディレクトリにあるほかのファイルを参考にして md ファイルを追加します - 例: `2038-1-19-doomsday.md` - 記事内容を記述します -- `npm textlint` と `npm mdlint` を実行し、エラーが出ないことを確認します +- `npm run textlint` と `npm run mdlint` を実行し、エラーが出ないことを確認します - もし誤検知があった場合はルールを修正するかレビュアーと相談してください - - エラー箇所をどうしても押し通したい場合はそこだけlintを無効化するよう記述してレビュアーに説明してください + - エラー箇所をどうしても押し通したい場合はそこだけ lint を無効化するよう記述してレビュアーに説明してください - 一通り追加と削除が終わったら `pull -r`, commit, push します ## 1. b. ページを編集する - 記事内容を記述します -- `npm textlint` と `npm mdlint` を実行し、エラーが出ないことを確認します +- `npm run textlint` と `npm run mdlint` を実行し、エラーが出ないことを確認します - もし誤検知があった場合はルールを修正するかレビュアーと相談してください - - エラー箇所をどうしても押し通したい場合はそこだけlintを無効化するよう記述してレビュアーに説明してください + - エラー箇所をどうしても押し通したい場合はそこだけ lint を無効化するよう記述してレビュアーに説明してください - 一通り編集が終わったら `pull -r`, commit, push します ## 2. 変更を提出する・レビューを受ける・マージしてもらう -文章に対するどのような変更も、必ずPull Requestを提出してドキュメント編集権限のあるメンバー最低1人にレビューを依頼します。 -このレビューに通ると変更がマージされ、公開されます。PRのタイトルや文章は丁寧に記述しましょう。詳細はScrapboxの[超説明・開発フロー](https://scrapbox.io/brain-hackers/%E8%B6%85%E8%AA%AC%E6%98%8E%E3%83%BB%E9%96%8B%E7%99%BA%E3%83%95%E3%83%AD%E3%83%BC)を参照してください。 +文章に対するどのような変更も、必ず Pull Request (PR) を提出してドキュメント編集権限のあるメンバー最低1人にレビューを依頼します。 +このレビューに通ると変更がマージされ、公開されます。PR のタイトルや文章は丁寧に記述しましょう。詳細は Scrapbox の[超説明・開発フロー](https://scrapbox.io/brain-hackers/%E8%B6%85%E8%AA%AC%E6%98%8E%E3%83%BB%E9%96%8B%E7%99%BA%E3%83%95%E3%83%AD%E3%83%BC)を参照してください。 -2021年12月現在、編集権限のあるメンバーは以下の通りです。 +2022年5月現在、編集権限のあるメンバーは以下の通りです。 - @puhitaku - @tka3320 +- @Sasakura-ayato -注意！GitHub の Brain Hackers organization のメンバーでない人はレビューを依頼できないので、 +注意！ GitHub の Brain Hackers organization のメンバーでない人はレビューを依頼できないので、 Discord にてメンバー追加依頼をしてメンバーになってから Pull Request を提出しましょう。 @@ -137,31 +140,31 @@ Wiki のページを生成している Jekyll は、md ファイルの名前か # 記述ルール -Wiki の体裁に関するルールを列挙します。コミットの前に従っているかチェックしてください。一部のルールはTextlintやmarkdownlintを使って機械的に調べたり修正できます。 +Wiki の体裁に関するルールを列挙します。コミットの前に従っているかチェックしてください。一部のルールは Textlint や markdownlint を使って機械的に調べたり修正できます。 ## 文体 -基本的には、技術文書のルールと同一です。助詞の使いすぎや表記ゆれはtextlintでチェックできますが、機械的に検知できる範囲は限られているためよく心得ておいてください。 +基本的には、技術文書のルールと同一です。助詞の使いすぎや表記ゆれは textlint でチェックできますが、機械的に検知できる範囲は限られているためよく心得ておいてください。 ### 「ですます」と「だ・である」は統一する -Linterによるチェック: **なし** +Linter によるチェック: **なし** Wiki 全体で「ですます」の形で統一します。 ### 依頼する時はできるだけ「します」で締める -Linterによるチェック: **なし** +Linter によるチェック: **なし** 「〇〇してください」は長いので、「します」で極力統一します。不自然に映る場合は「してください」や「しましょう」を使っても OK です。この文書でも実際にどちらも使用しています。 ### 繰り返しや冗長な表現をなくす -Linterによるチェック: textlint（部分的） +Linter によるチェック: textlint（部分的） 冗長な表現を組み込んでしまうことは多いので、極限まで削ります。 「など」「いろいろ」「といった」「〇〇できます」は使いがちですので特に気を付けましょう。 @@ -173,7 +176,7 @@ Linterによるチェック: textlint（部分的） ### 括弧は基本的に使わない -Linterによるチェック: **なし** +Linter によるチェック: **なし** どうしても必要な場合は、名詞の別名や補足といった1〜2単語で済む体言を入れるだけにします。 @@ -184,14 +187,14 @@ Linterによるチェック: **なし** ### 箇条書きには句読点を入れない -Linterによるチェック: **なし** +Linter によるチェック: **なし** 箇条書きは段落を表現する道具ではありません。よって、内容が極力短くなるようにしつつ、句読点を置かないようにします。 ### 感情を排除する -Linterによるチェック: **なし** +Linter によるチェック: **なし** 極力スムーズに読める文章になるには、感情的表現を取り除く事が必須です。 文章は技術文書（レポート）のような無味乾燥なものにし、感情は Discord で共有しましょう。 @@ -199,7 +202,7 @@ Linterによるチェック: **なし** ### コードブロックや画像と文章の関わりを示す -Linterによるチェック: **なし** +Linter によるチェック: **なし** 「以下にコマンド例を示します」などのように、文章と以下に連なる要素を関連付けます。 @@ -207,7 +210,7 @@ Linterによるチェック: **なし** ## Markdown Markdown はリッチなレンダリングがなくとも読めるシンタックスが特徴です。これを念頭に置いて、以下のルールに従ってください。 -一部はmarkdownlintによって違反を検知できます。ここにない細かなルールはmarkdownlintの指示に従ってください。 +一部は markdownlint によって違反を検知できます。ここにない細かなルールは markdownlint の指示に従ってください。 ### 必ずプレビューして確認する @@ -232,7 +235,7 @@ git config --global core.autocrlf input ### 適切な空行を入れる -Linterによるチェック: あり +Linter によるチェック: あり 以下の箇所には1行空行を入れます。 @@ -252,9 +255,9 @@ Linterによるチェック: あり ### 適切な空白を入れる -Linterによるチェック: **なし** +Linter によるチェック: **なし** -プレーンテキスト以外の要素の前後には適切な空白を入れ、表示がおかしくなるリスクを減らしましょう。この文書はWikiでの表示に限られるため空白を欠いても大丈夫ですが、エディタでのシンタックスハイライトに失敗することがありますので気を付けましょう。 +プレーンテキスト以外の要素の前後には適切な空白を入れ、表示がおかしくなるリスクを減らしましょう。この文書は Wiki での表示に限られるため空白を欠いても大丈夫ですが、エディタでのシンタックスハイライトに失敗することがありますので気を付けましょう。 :x: 悪い例1: `1.あいうえお` @@ -267,7 +270,7 @@ Linterによるチェック: **なし** ### コードスパンとコードブロックを使い分ける -Linterによるチェック: **なし** +Linter によるチェック: **なし** コードスパンとは、`` `ident` ``のように行の中に等幅で文字を入れるスパン要素を指します。 @@ -292,7 +295,7 @@ ls -l ### 明示的改行はバックスラッシュで行う -Linterによるチェック: **なし** +Linter によるチェック: **なし** この節でいう明示的改行とは Hard line breaks のことで、空行による段落区切りや単一の LF による Soft line break ではなく確実に改行を入れることを指します。必要でない限りは使わないことが望ましいです。