7.4 KiB
| title | categories | tags | |||
|---|---|---|---|---|---|
| Wiki の編集方法とルール |
|
|
準備
WikiをCloneします。
$ git clone git@github.com:brain-hackers/wiki.brainux.org.git
各種操作
1. a. ページを追加・削除する
- 新たにブランチを作成する
- 後で Pull Request として提出するため、
masterブランチには直接コミットしないでください
- 後で Pull Request として提出するため、
_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 をプレビューできる環境を用意して確認してからコミットしましょう。例えば Grip が便利です。
改行コードは 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つを入れる方法とバックスラッシュを入れる方法がありまず。前者は通常不可視な上に意味合いがわかりづらいため、バックスラッシュを使用します。