mirror of
https://github.com/brain-hackers/README
synced 2025-03-13 03:22:21 +09:00
Wikiの記述ルールを追加
Takumi Sueda
parent
e0616f37f1
commit
83459e59a2
121
Wikiの編集方法.md
121
Wikiの編集方法.md
@ -8,6 +8,20 @@
|
||||
- [ページを編集する](#%E3%83%9A%E3%83%BC%E3%82%B8%E3%82%92%E7%B7%A8%E9%9B%86%E3%81%99%E3%82%8B)
|
||||
- [各文章内の目次生成](#%E5%90%84%E6%96%87%E7%AB%A0%E5%86%85%E3%81%AE%E7%9B%AE%E6%AC%A1%E7%94%9F%E6%88%90)
|
||||
- [ファイル名とサイドバーの関係](#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E5%90%8D%E3%81%A8%E3%82%B5%E3%82%A4%E3%83%89%E3%83%90%E3%83%BC%E3%81%AE%E9%96%A2%E4%BF%82)
|
||||
- [記述ルール](#%E8%A8%98%E8%BF%B0%E3%83%AB%E3%83%BC%E3%83%AB)
|
||||
- [文体](#%E6%96%87%E4%BD%93)
|
||||
- [「ですます」と「だ・である」は統一する](#%E3%81%A7%E3%81%99%E3%81%BE%E3%81%99%E3%81%A8%E3%81%A0%E3%83%BB%E3%81%A7%E3%81%82%E3%82%8B%E3%81%AF%E7%B5%B1%E4%B8%80%E3%81%99%E3%82%8B)
|
||||
- [繰り返しや冗長な表現をなくす](#%E7%B9%B0%E3%82%8A%E8%BF%94%E3%81%97%E3%82%84%E5%86%97%E9%95%B7%E3%81%AA%E8%A1%A8%E7%8F%BE%E3%82%92%E3%81%AA%E3%81%8F%E3%81%99)
|
||||
- [カッコは基本的に使わない](#%E3%82%AB%E3%83%83%E3%82%B3%E3%81%AF%E5%9F%BA%E6%9C%AC%E7%9A%84%E3%81%AB%E4%BD%BF%E3%82%8F%E3%81%AA%E3%81%84)
|
||||
- [箇条書きには句読点を入れない](#%E7%AE%87%E6%9D%A1%E6%9B%B8%E3%81%8D%E3%81%AB%E3%81%AF%E5%8F%A5%E8%AA%AD%E7%82%B9%E3%82%92%E5%85%A5%E3%82%8C%E3%81%AA%E3%81%84)
|
||||
- [感情を排除する](#%E6%84%9F%E6%83%85%E3%82%92%E6%8E%92%E9%99%A4%E3%81%99%E3%82%8B)
|
||||
- [コードブロックや画像と文章の関わりを示す](#%E3%82%B3%E3%83%BC%E3%83%89%E3%83%96%E3%83%AD%E3%83%83%E3%82%AF%E3%82%84%E7%94%BB%E5%83%8F%E3%81%A8%E6%96%87%E7%AB%A0%E3%81%AE%E9%96%A2%E3%82%8F%E3%82%8A%E3%82%92%E7%A4%BA%E3%81%99)
|
||||
- [Markdown](#markdown)
|
||||
- [必ずプレビューして確認する](#%E5%BF%85%E3%81%9A%E3%83%97%E3%83%AC%E3%83%93%E3%83%A5%E3%83%BC%E3%81%97%E3%81%A6%E7%A2%BA%E8%AA%8D%E3%81%99%E3%82%8B)
|
||||
- [改行コードは LF に統一する](#%E6%94%B9%E8%A1%8C%E3%82%B3%E3%83%BC%E3%83%89%E3%81%AF-lf-%E3%81%AB%E7%B5%B1%E4%B8%80%E3%81%99%E3%82%8B)
|
||||
- [適切な空行を入れる](#%E9%81%A9%E5%88%87%E3%81%AA%E7%A9%BA%E8%A1%8C%E3%82%92%E5%85%A5%E3%82%8C%E3%82%8B)
|
||||
- [コードスパンとコードブロックを使い分ける](#%E3%82%B3%E3%83%BC%E3%83%89%E3%82%B9%E3%83%91%E3%83%B3%E3%81%A8%E3%82%B3%E3%83%BC%E3%83%89%E3%83%96%E3%83%AD%E3%83%83%E3%82%AF%E3%82%92%E4%BD%BF%E3%81%84%E5%88%86%E3%81%91%E3%82%8B)
|
||||
- [明示的改行はバックスラッシュで行う](#%E6%98%8E%E7%A4%BA%E7%9A%84%E6%94%B9%E8%A1%8C%E3%81%AF%E3%83%90%E3%83%83%E3%82%AF%E3%82%B9%E3%83%A9%E3%83%83%E3%82%B7%E3%83%A5%E3%81%A7%E8%A1%8C%E3%81%86)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
@ -62,3 +76,110 @@ $ git clone https://github.com/brain-hackers/README.wiki.git
|
||||
サイドバーの制約から、 `＞` はファイル名の中で2回まで使えます。 `あ.md` や `あ＞い＞う.md` は valid ですが、 `あ＞い＞う＞え.md` は invalid です。
|
||||
|
||||
ページ名にハイフン `-` (Hyphen-Minus, U+002D) を使いたい場合、GitHub Wiki はハイフンを空白文字と同等に扱うため、そのままファイル名に入れると空白に置き換わって表示されてしまいます。これを回避するために、よく似た別なUnicode文字 `‐` (Hyphen, U+2010) を使ってください（左からコピペして使うと楽）。`U‐Boot` をタイトルに含む記事が実際の例です。
|
||||
|
||||
|
||||
# 記述ルール
|
||||
Wiki の体裁について以下にルールを列挙します。コミットの前にこれらに従っているかチェックしてください。Textlint はまだありません。
|
||||
|
||||
|
||||
## 文体
|
||||
基本的には、技術文書のルールと同一です。
|
||||
|
||||
|
||||
### 「ですます」と「だ・である」は統一する
|
||||
Wiki 全体で「ですます」の形で統一します。
|
||||
|
||||
|
||||
### 繰り返しや冗長な表現をなくす
|
||||
冗長な表現を組み込んでしまうことは多いので、極限まで削ります。
|
||||
「など」「いろいろ」「といった」「〇〇することができます」は使いがちですので特に気をつけましょう。
|
||||
|
||||
- 悪い例: このコマンドを使えば、Linux を起動することなどが可能です。
|
||||
- 良い例: このコマンドで、Linux を起動できます。
|
||||
|
||||
|
||||
### カッコは基本的に使わない
|
||||
どうしても必要な場合は、名詞の別名や補足といった1〜2単語で済む体言を入れるだけにします。
|
||||
|
||||
- 悪い例: Linux マシン（Ubuntu か Debian が入っていることが望ましい）を用意します。
|
||||
- 良い例: Ubuntu か Debian がインストールされた Linux マシンを用意します。
|
||||
|
||||
|
||||
### 箇条書きには句読点を入れない
|
||||
箇条書きは段落を表現する道具ではありません。よって、内容が極力短くなるようにしつつ、句読点を置かないようにします。
|
||||
ちなみに、このページの良い例悪い例の例示では例外的に句読点を使っています。通常は使わないようにしましょう。
|
||||
|
||||
|
||||
### 感情を排除する
|
||||
極力スムーズに読める文章になるには、感情的表現を取り除く事が必須です。
|
||||
文章は技術文書（レポート）のような無味乾燥なものにし、感情は Discord で共有しましょう。
|
||||
|
||||
|
||||
### コードブロックや画像と文章の関わりを示す
|
||||
「以下にコマンド例を示します」などのように、文章と以下に連なる要素を関連付けます。
|
||||
|
||||
|
||||
## Markdown
|
||||
Markdown はリッチなレンダリングがなくとも読めるシンタックスが特徴です。これを念頭に置いて、以下のルールに従ってください。
|
||||
|
||||
|
||||
### 必ずプレビューして確認する
|
||||
ブラウザで文書を編集すると、コミット前に文書を HTML にレンダーするプレビューが利用可能です。ミスがないか確認してからコミットしましょう。
|
||||
|
||||
ローカルのコンソールやエディタで書く場合も、Markdown をプレビューできる環境を用意して確認してからコミットしましょう。例えば [Grip](https://github.com/joeyespo/grip) が便利です。
|
||||
|
||||
|
||||
### 改行コードは LF に統一する
|
||||
Windows で特に気をつけましょう。Git は[コミット時に改行コードを LF のみに強制](https://qiita.com/uggds/items/00a1974ec4f115616580)できます。
|
||||
|
||||
`git config` で
|
||||
|
||||
```
|
||||
git config --global core.autocrlf input
|
||||
```
|
||||
|
||||
と設定すると、コミット時に Unix style でコミットできます。
|
||||
|
||||
|
||||
### 適切な空行を入れる
|
||||
以下の箇所には1行空行を入れます。
|
||||
|
||||
- 段落と段落の間
|
||||
- プレーンテキストとプレーンテキスト以外の要素の間
|
||||
- 箇条書き
|
||||
- テーブル
|
||||
- 図
|
||||
- コードブロック
|
||||
- 引用
|
||||
|
||||
以下の箇所には2行空行を入れます。
|
||||
|
||||
- 節と節の間
|
||||
|
||||
|
||||
### コードスパンとコードブロックを使い分ける
|
||||
コードスパンとは、`` `ident` ``のように行の中に等幅で文字を入れるスパン要素を指します。
|
||||
|
||||
コードブロックとは
|
||||
|
||||
```
|
||||
echo foo
|
||||
```
|
||||
|
||||
のように新しい段落で等幅に文字を入れるブロック要素を指します。
|
||||
|
||||
コードスパンはコードの識別子やコマンド名の例示に使い、コードブロックは複数行のプログラムや完全なコマンド（実行可能な文字列）の例示に使用します。
|
||||
|
||||
例1: `ls` コマンドには `-l` というオプションがあります。
|
||||
|
||||
例2: `ls` コマンドでファイルの詳細情報を表示するには、以下のように実行します。
|
||||
|
||||
```sh
|
||||
ls -l
|
||||
```
|
||||
|
||||
|
||||
### 明示的改行はバックスラッシュで行う
|
||||
この節でいう明示的改行とは [Hard line breaks](https://github.github.com/gfm/#hard-line-breaks) のことで、空行による段落区切りや単一の LF による Soft line break ではなく確実に改行を入れることを指します。必要でない限りは使わないことが望ましいです。
|
||||
|
||||
明示的な改行の入れ方には行末にスペース2つを入れる方法とバックスラッシュを入れる方法がありまず。前者は通常不可視な上に意味合いがわかりづらいため、バックスラッシュを使用します。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user