Skip to content

Instantly share code, notes, and snippets.

@LambdaNote LambdaNote/writing.md Secret
Last active Apr 7, 2019

Embed
What would you like to do?
記事の書き方

記事の書き方

記事の執筆には、Markdown形式を利用してください。 Markdownにはさまざまな流派がありますが、GitHub Flavored Markdown(https://github.github.com/gfm/ )をベースとした書式を採用します。

書籍を執筆するための形式として考えると、Markdownには機能的で不足している面が多々あります。 しかし、次のような利点があるので、Markdownを採用することにします。

  • 最低限の構造しかないので、見た目でごまかせる余地が少ない
  • 原稿を著者自身が再利用してもらいやすくしたい
  • ラムダノートで販売する際のスタイルは、原稿の形式がなんであれ、別に考えなければならない

以下では、節や項といった記事の大構造、および、段落やコードや図表といった記事の小構造について、 執筆にあたって気を付けていただきたいことや記述方法のお願いをまとめます。

記事の大構造

記事全体をどう構成するかは、解説する内容や目的(情報の要約かチュートリアルか、など)によって異なります。 論文ではないので定型はありませんが、困ったら下記の構成に沿って考えてみてください。

  1. 何のために記事を書くか(問題意識を読者と共有)
  2. 解説の前提となる情報の整理(読者を記事の土俵に上げる)
  3. 主たる解説
  4. まとめ、練習問題、関連情報、参考資料など

最上位の階層に対する見出しには、都合により、Markdownのレベル2( ## )を利用してください。

通常、大構造の内部は、さらに構造化したほうが読みやすくなります。 しかし、構造が深くなると読者が迷子になりやすいので、大構造の下位は原則として1段階のみとします。

上記をふまえると、記事全体の構造は下記のようになります。

## セクション1の見出し

段落要素

### サブセクション1の見出し

段落要素

### サブセクション2の見出し

段落要素

## セクション2の見出し

段落要素

…

記事の小構造

記事の本文のほとんどは、段落です。 段落は、文章の意味の最小単位といえます。

以下では、段落および段落を補完する箇条書きや図表、コードブロックなどの要素についてまとめます。

段落の書き方

段落を書くときは、以下の2点を気にかけてください。

  • ある段落を1つ取り出したとき、その内容を簡潔に要約できるか
  • 段落と段落の関係は、全体として伝えたい内容にとって適切か

上記の2点を達成するために、編集でかなり大胆な本文の修正を提案する場合があります。 そのため、差分が見やすくなるように、段落内ではなるべく句点ごとに改行を挿入してください。

段落は次の要領で記述します。

空行から次の空行までの文章が、1つの段落になります。
途中で改行しても、新しい段落にはなりません。
むしろこまめに改行したほうが、差分がとりやすくなります。

段落内および段落間をうまく構成すると、言いたかったことが伝わりやすい記事になります。
各段落の内容を自分で要約しながら自分で読み返してみるのがおすすめです。

本文で利用可能な記法については、本稿の後半の「本文の書き方」の項を参照してください。

箇条書き

段落の主張を見やすく整理することを目的として、必要に応じて箇条書きを利用してください。 言い換えると、箇条書きはあくまでも段落に従属するものとし、箇条書きのみで説明が終わることがないように注意してください。

箇条書きには、連番がつかないものと、つくものがあります。それぞれ以下の要領で使います。

  • 箇条書き(Unordered List)

    基本的には連番なしの箇条書きを使います。

    * 項目1
      * サブ項目は1階層のみ可
    * 項目2
      1. 連番つき箇条書きのサブ項目の例
  • 連番つき箇条書き(Ordered List)

    項目間の順序に意味がある場合や、あとで番号で参照したい場合は、連番つき箇条書きを使います。

    1. 項目1
    2. 項目2

図表

段落の説明を補足することを目的として、必要に応じて図表を利用してください。

画像は以下の要領で配置します。なるべく見出しを付けてください。

![画像見出し](/path/to/image.data)

表の書式についてはGitHubによるガイド(https://guides.github.com/features/mastering-markdown/ )などを参照してください。

コードブロック

技術書において、プログラムの一部を示したコードブロックは主要な解説対象です。 したがって、コードブロックの提示をもって説明を終わらせるのではなく、そのコードについて日本語で説明を施すようしてください。 具体的には、次のような内容を説明してください。

  1. なぜ本文のこの位置でそのコードを提示するのか
  2. 何を実現するコードなのか
  3. コードの各部にはどのような役割があり、どのように動作するか

プログラミング言語のコメント機能を使ってコード中に動作の説明を付記するのは、上記のうち3のみにしてください。 コメント機能によるコードの動作の補足説明は、コードの中身をしっかり読む段階にある読者にとってはとても有用ですが、初見ではあまり読まれません。 特に上記の1と2の内容については、本文でしっかりと解説するようにしてください。

コードブロックを示すときは、原則として下記の書式を使ってください。

```
Hello World!
```

引用

他の文書からの引用には、下記の書式を使ってください。

本文

> 引用文
> 引用文

本文

引用のみで説明を済ませることは絶対にしないでください。 引用は、本文を補足する目的に限ります。出典も必ず明記してください。

補足やコラム

箇条書きの項目に対し、インデントで説明を付け加えることで、段落に対する補足やコラムを構成します。 見出しの行頭に [コラム][補足] などと付記してください。

下記は、箇条書きとコードブロックを含むコラムの例です。

* [コラム]見出しつき箇条書きの見出し

  コラムの本文は、インデントさせた段落として執筆してください。
  コラム内にも箇条書きや図表、コードなどが挿入できます。

  * サブ項目a
  * サブ項目b
  
  ```
  Hello World!
  ```

  コラムの終わりには、空行+インデントしていない行が必要です。

ここからは次の段落本文になります。

ディスプレイ数式

$$ のみの行から、次の $$ のみの行までの間に、下記の要領でLaTeXの書式を記述してください。 どのようなLaTeXコマンドに対応するかは未定なので、そのつど相談してください。

$$
\hoge
$$

この形式で数式以外のもの(図表など)を入れ込むことはしないでください。

本文の書き方

段落などを構成する本文は、敬体でも常体でもかまいません。

以下では、本文における装飾や約物の使い方などを簡単にまとめます。 これ以上に細かいシンタックスやレギュレーションを設定する予定はありません。

本文に対する装飾

本文中では、文字列に対する装飾として、下記の書式のみを利用してください( は半角スペース U+0020 を意味します)。

  • ␣**文字列**␣ (文字列を強調)
  • ␣`文字列`␣ (文字列を等幅で表示。` を含める場合には、連続するバックチックで囲む ␣`` `を含む文字列``␣ という書式を使う)
  • 文字列([URL](URL)) (文字列に対して外部のURLを参照。「URL」の部分は同一の内容を入れる。 [文字列](URL) のようなURLを見せないリンク形式は不可)
  • 文字列(注:注釈の文章) (文字列に対する注釈。書籍などでは脚注として扱います)
  • ␣$TeX書式$␣ (インライン数式)
  • 行頭の マーク (行末までを、本文ではなくコメントとして扱う。行頭以外の マークは非コメント)

句読点

とくにこだわりがなければ、 を推奨します。 、もしくは などでもかまいませんが、編集で に変更する可能性があります。

いわゆる半角の . および , は句読点としては使わないでください。

疑問符および感嘆符をどうしても使う場合は、それぞれ全角記号を使用してください。 すなわち、 U+FF1F)および U+FF01)を使ってください。

コロンやセミコロンを使う場合も、全角とします。 すなわち、 U+FF1A)および U+FF1B)を利用してください。

和欧文間のスペースについて

日本語の文字と英数字間にスペースは入れないでください。

括弧類について

本文中での補足には、なるべく全角の丸括弧 および を使ってください。 それぞれ、具体的には U+FF08 および U+FF09 です。

本文中で文字列を意味的に切り出したい場合には、基本的に鍵括弧( および )を使ってください。 言い換えると、日本語を切り出す際にダブルクォーテーションは使わないでください。

書式に関してサポートしないこと

書式に関して期待されるであろう事項のうち、下記の点に関しては最初からサポートしないものとします。

一定の見た目

WebブラウザやPDFで、上記の書式がどのような見た目で表示されるかは、書式から一意には定めないことにします。 GitHubに貼り付ければ、そのWebサイト上で一定のスタイルでレンダリングされると思いますが、そこでの表示を整えることはがんばらないでください。

そもそも上記の定義には、GitHub上で意図したようにレンダリングされない要素もいくつかあります。 たとえば、そもそも数式に関しては、GitHubで意図通りにレンダリングされることはありません。 コメントについても同様です。 脚注についても、本文以外の場所に表示されるようなものはありません。

参照、参考文献

記事中での相互参照には、Pandocの記法を使います。

  • コードブロックへの参照 https://pandoc.org/MANUAL.html#fenced-code-blocks

    • コードブロックに対するアンカー例
    ```{#lst:code1 caption="キャプション"}
    (コード)
    ```
    
    • コードブロックへのリンク例
    ……。[-@lst:code1]に〇〇の例を示す。
    
  • 図への参照

    • 図に対するアンカー例
    ![キャプション](images/foobar.png){#fig:foobar}
    
    • 図へのリンク例
    ……。図[-@fig:foobar]に〇〇の例を示す。
    
  • 参考文献 refs.bib ファイルに、BibTeXの形式で書誌情報ファイルを用意します。

    • bib
    @article{foobar2019,
      author = {Doe, John.},
      title = {FooBar},
      year = {2019},
      url = {http://example.com/foobar},
      ...
    } 
    
    • citation
    …… [@foobar2019]。
    

図とコードブロックのキャプション

図とコードブロックについては、可能なかぎり上記の容量でキャプションを付記してください。 ただし、GitHub Fravered Markdownの書式ではないので、GitHub上のプレビューにはキャプションが表示されません。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.