wiki.brainux.org/_posts/2021-12-04-meta-how-to-edit-wiki.md

title	categories	tags	excerpt
Wiki の編集方法とルール	Meta	Wiki メンバー向け

準備

GitHubにログインした状態でWikiをcloneします。

$ 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系の最新バージョンをインストールしてください。

$ sudo apt install ruby-full

Rubyがインストールできたら、以下のようにしてRuby 2.7が実行されることを確認します。

$ ruby -v
ruby 2.7.0p0 (2019-12-25 revision 647ee6f091) [x86_64-linux-gnu]

次に手元でのビルドに必要な依存関係をインストールします。

$ cd wiki.brainux.org
$ bundle install

ビルドとプレビューができることを確認します。下記のように bundle exec jekyll serve を実行すると localhost:4000 でサーバーが 起動している旨のメッセージが出るので、メッセージが見え次第ブラウザで localhost:4000 を開いてプレビューできます。

$ bundle exec jekyll serve
Configuration file: /Users/takumi/dev/brain/wiki.brainux.org/_config.yml
            Source: /Users/takumi/dev/brain/wiki.brainux.org
       Destination: /Users/takumi/dev/brain/wiki.brainux.org/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
      Remote Theme: Using theme mmistakes/minimal-mistakes
       Jekyll Feed: Generating feed for posts
   GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.
                    done in 53.672 seconds.
 Auto-regeneration: enabled for '/Users/takumi/dev/brain/wiki.brainux.org'
    Server address: http://127.0.0.1:4000
  Server running... press ctrl-c to stop.

次に、Textlintとmarkdownlintを使うためにNode.jsとパッケージをインストールします。

$ cd wiki.brainux.org
$ npm install

Node.jsのインストール方法とバージョンは動けば何でも良いです。まずはパッケージマネージャーでインストールしたNode.jsを使ってみて、上手く行かなければnodeenv（nodenvではない！）を使う以下の方法を試してください。nodeenvでインストールした場合は、毎回envをactivateするのを忘れないでください。

$ pip install nodeenv
$ nodeenv -n 16.13.2 env
$ source ./env/bin/activate
(env) $ npm install

Textlintを動かして、正常にlintされるか試します。自動修正はnpm run fixで発動できますが、意図しない修正が起こる可能性があるためあまりおすすめしません。

$ npm run lint
$ npm run fix  # お好みで

markdownlintを動かして、正常にlintされるか試します。

$ npm run mdlint

各種操作

1. a. ページを追加・削除する

• 新たにブランチを作成する
  • 後で Pull Request として提出するため、master ブランチには直接コミットしないでください
• _posts ディレクトリにある他のファイルを参考にして md ファイルを追加します
  • 例: 2038-1-19-doomsday.md
• 記事内容を記述します
• ひととおり追加と削除が終わったら pull -r, commit, push します

1. b. ページを編集する

• 記事内容を記述します
• ひととおり編集が終わったら pull -r, commit, push します

2. 変更を提出する・レビューを受ける・マージしてもらう

文章に対するどのような変更も、必ずドキュメント編集権限のあるメンバー最低1人にレビューを依頼します。 このレビューに通ると変更がマージされ、公開されます。

2021年12月現在、編集権限のあるメンバーは以下の通りです。

• @puhitaku
• @tka3320

注意！GitHub の Brain Hackers organization のメンバーでない人はレビューを依頼できないので、 Discord にてメンバー追加依頼をしてメンバになってから Pull Request を提出しましょう。

ファイル名のルール

Wiki のページを生成している Jekyll は、md ファイルの名前から記事の日付や URL を生成します。以下のすべての条件を満たすようにしましょう。

• YYYY-MM-DD-{英字とハイフンでできたタイトル}.md の形式にする
• URL が冗長になるので日本語は使わない

記述ルール

Wiki の体裁について以下にルールを列挙します。コミットの前にこれらに従っているかチェックしてください。Textlint はまだありません。

文体

基本的には、技術文書のルールと同一です。

「ですます」と「だ・である」は統一する

Wiki 全体で「ですます」の形で統一します。

依頼する時はできるだけ「します」で締める

「〇〇してください」は長いので、「します」で極力統一します。不自然に映る場合は「してください」や「しましょう」を使っても OK です。この文書でも実際にどちらも使用しています。

繰り返しや冗長な表現をなくす

冗長な表現を組み込んでしまうことは多いので、極限まで削ります。 「など」「いろいろ」「といった」「〇〇することができます」は使いがちですので特に気をつけましょう。

❌ 悪い例: このコマンドを使えば、Linux を起動することなどが可能です。

⭕ 良い例: このコマンドで、Linux を起動できます。

カッコは基本的に使わない

どうしても必要な場合は、名詞の別名や補足といった1〜2単語で済む体言を入れるだけにします。

❌ 悪い例: Linux マシン（Ubuntu か Debian が入っていることが望ましい）を用意します。

⭕ 良い例: Ubuntu か Debian がインストールされた Linux マシンを用意します。

箇条書きには句読点を入れない

箇条書きは段落を表現する道具ではありません。よって、内容が極力短くなるようにしつつ、句読点を置かないようにします。

感情を排除する

極力スムーズに読める文章になるには、感情的表現を取り除く事が必須です。 文章は技術文書（レポート）のような無味乾燥なものにし、感情は Discord で共有しましょう。

コードブロックや画像と文章の関わりを示す

「以下にコマンド例を示します」などのように、文章と以下に連なる要素を関連付けます。

Markdown

Markdown はリッチなレンダリングがなくとも読めるシンタックスが特徴です。これを念頭に置いて、以下のルールに従ってください。

必ずプレビューして確認する

ブラウザで文書を編集すると、コミット前に文書を HTML にレンダーするプレビューが利用可能です。ミスがないか確認してからコミットしましょう。

ローカルのコンソールやエディタで書く場合も、Markdown をプレビューできる環境を用意して確認してからコミットしましょう。

改行コードは LF に統一する

Windows で特に気をつけましょう。Git はコミット時に改行コードを LF のみに強制できます。

git config で

git config --global core.autocrlf input

と設定すると、コミット時に Unix style でコミットできます。

適切な空行を入れる

以下の箇所には1行空行を入れます。

• 段落と段落の間
• プレーンテキストとプレーンテキスト以外の要素の間
  • 節タイトル
  • 箇条書き
  • テーブル
  • 図
  • コードブロック
  • 引用

以下の箇所には2行空行を入れます。

• 節と節の間

適切な空白を入れる

プレーンテキスト以外の要素の前後に適切な空白がないと表示がおかしくなるケースがあります。この文書は GitHub での表示に限られるため空白がなくても大丈夫ですが、エディタでのシンタックスハイライトが上手くいかなくなることがありますので気をつけましょう。

❌ 悪い例1: 1.あいうえお

⭕ 良い例1: 1. あいうえお

❌ 悪い例2: このコマンドには`-a`という引数を渡します。

⭕ 良い例2: このコマンドには `-a` という引数を渡します。

コードスパンとコードブロックを使い分ける

コードスパンとは、`ident`のように行の中に等幅で文字を入れるスパン要素を指します。

コードブロックとは

echo foo

のように新しい段落で等幅に文字を入れるブロック要素を指します。

コードスパンはコードの識別子や短いコマンドの例示に使い、コードブロックは複数行のプログラムや長いコマンドの例示に使用します。

例1: ls コマンドには -l というオプションがあります。

例2: ls コマンドでファイルの詳細情報を表示するには、以下のように実行します。

ls -l

明示的改行はバックスラッシュで行う

この節でいう明示的改行とは Hard line breaks のことで、空行による段落区切りや単一の LF による Soft line break ではなく確実に改行を入れることを指します。必要でない限りは使わないことが望ましいです。

明示的な改行の入れ方には行末にスペース2つを入れる方法とバックスラッシュを入れる方法がありまず。前者は通常不可視な上に意味合いがわかりづらいため、バックスラッシュを使用します。