gistfile1.adoc

AsciiDoc を覚えて綺麗なドキュメントを作ろう

AsciiDoc について

AsciiDoc（アスキードック）は Markdown のように書ける軽量マークアップ言語です。

例えば表であれば下記のようなコードで作ることができます。

ソースコード

[options="header"]
.Example Table
|===
|列1 |列2 |列3
|値1 |値2 |値3
|===

これは HTML の <table> に変換されて出力されます。

Table 1. Example Table

列1	列2	列3
値1	値2	値3

ブラウザで HTML 化されたコードを見てみましょう。HTML に慣れている人ならこのコードだけで表をイメージできるかもしれませんが知らない人にとってはちょっと難しいですね。

<table><thead>
<tr>
<th>列1</th>
<th>列2</th>
<th>列3</th>
</tr>
</thead>
<tbody>
<tr>
<td><p>値1</p></td>
<td><p>値2</p></td>
<td><p>値3</p></td>
</tr>
</tbody>
</table>

AsciiDoc には表作成の他にも見出しやセクション等を表現するためのコードも用意されていますがすべてを覚える必要はありません。というのも、すべてを覚えなくてもドキュメントは作れるからです。

「そもそもマークアップ言語って何？」という疑問もあるかもしれませんがそれも少しずつ覚えていきましょう。

ドキュメント作成をはじめる前に

ここではドキュメントの作成方法や AsciiDoc などの説明をしていきますが、あくまで私個人の文章の書き方であり、これらが適切なドキュメントの作り方ではないということを頭に入れておいてください。企業においてはドキュメント作成のルールやテンプレートが用意されていることもありますし、新聞社や出版社ともなればより厳しいルールがあります。

ドキュメントを作成するにあたって最も大事なことは「読む人に伝わること」です。このことを常に意識しましょう。