From 1e02a89d861c32d207a059a5725ae7e7584b4223 Mon Sep 17 00:00:00 2001 From: Takumi Sueda Date: Wed, 12 Jan 2022 03:38:37 +0900 Subject: [PATCH] Describe about if linters detect the violation of rules --- _posts/2021-12-04-meta-how-to-edit-wiki.md | 24 +++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) 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 f4f7ee1..6e74d0e 100644 --- a/_posts/2021-12-04-meta-how-to-edit-wiki.md +++ b/_posts/2021-12-04-meta-how-to-edit-wiki.md @@ -147,16 +147,22 @@ Wiki の体裁に関するルールを列挙します。コミットの前に従 ### 「ですます」と「だ・である」は統一する +Linterによるチェック: **なし** + Wiki 全体で「ですます」の形で統一します。 ### 依頼する時はできるだけ「します」で締める +Linterによるチェック: **なし** + 「〇〇してください」は長いので、「します」で極力統一します。不自然に映る場合は「してください」や「しましょう」を使っても OK です。この文書でも実際にどちらも使用しています。 ### 繰り返しや冗長な表現をなくす +Linterによるチェック: textlint（部分的） + 冗長な表現を組み込んでしまうことは多いので、極限まで削ります。 「など」「いろいろ」「といった」「〇〇できます」は使いがちですので特に気を付けましょう。 @@ -165,7 +171,9 @@ Wiki 全体で「ですます」の形で統一します。 :o: 良い例: このコマンドで、Linux を起動できます。 -### 括弧基本的に使わない +### 括弧は基本的に使わない + +Linterによるチェック: **なし** どうしても必要な場合は、名詞の別名や補足といった1〜2単語で済む体言を入れるだけにします。 @@ -176,17 +184,23 @@ Wiki 全体で「ですます」の形で統一します。 ### 箇条書きには句読点を入れない +Linterによるチェック: **なし** + 箇条書きは段落を表現する道具ではありません。よって、内容が極力短くなるようにしつつ、句読点を置かないようにします。 ### 感情を排除する +Linterによるチェック: **なし** + 極力スムーズに読める文章になるには、感情的表現を取り除く事が必須です。 文章は技術文書（レポート）のような無味乾燥なものにし、感情は Discord で共有しましょう。 ### コードブロックや画像と文章の関わりを示す +Linterによるチェック: **なし** + 「以下にコマンド例を示します」などのように、文章と以下に連なる要素を関連付けます。 @@ -217,6 +231,8 @@ git config --global core.autocrlf input ### 適切な空行を入れる +Linterによるチェック: あり + 以下の箇所には1行空行を入れます。 - 段落と段落の間 @@ -235,6 +251,8 @@ git config --global core.autocrlf input ### 適切な空白を入れる +Linterによるチェック: **なし** + プレーンテキスト以外の要素の前後には適切な空白を入れ、表示がおかしくなるリスクを減らしましょう。この文書はWikiでの表示に限られるため空白を欠いても大丈夫ですが、エディタでのシンタックスハイライトに失敗することがありますので気を付けましょう。 :x: 悪い例1: `1.あいうえお` @@ -248,6 +266,8 @@ git config --global core.autocrlf input ### コードスパンとコードブロックを使い分ける +Linterによるチェック: **なし** + コードスパンとは、`` `ident` ``のように行の中に等幅で文字を入れるスパン要素を指します。 コードブロックとは @@ -271,6 +291,8 @@ ls -l ### 明示的改行はバックスラッシュで行う +Linterによるチェック: **なし** + この節でいう明示的改行とは Hard line breaks のことで、空行による段落区切りや単一の LF による Soft line break ではなく確実に改行を入れることを指します。必要でない限りは使わないことが望ましいです。 明示的な改行の入れ方には行末にスペース2つを入れる方法とバックスラッシュを入れる方法がありまず。前者は通常不可視な上に意味合いがわかりづらいため、バックスラッシュを使用します。