あらど島あらど島

DOCUMENTATION AS CODE Asciidoctorによる継続的ドキュメント開発

  • ダウンロード商品
    ¥ 1,000

B5 / 54p / PDF / フルカラー Asciidoctorを使って継続的にドキュメント開発するための本です。 1. なぜMarkdownではなくAsciidoctorなのか? Markdownには以下の問題があります。 * 文法の方言が多く、他人の作成したドキュメントの表示が崩れる。 * テーブル表現が弱く、Excelから脱出できない。 Asciidoctorは方言がありません。他人の作成したドキュメントも同じように表示できます。また、行結合などテーブル表現が豊かなのでExcelに近い表現が可能です。 また、MarkdownとAsciidoctorは競合しません。個人メモやWikiなどはMarkdownで良いです。複数人で継続的に開発する場合においてAsciidoctorは効果を発揮します。 2. ドキュメント開発におけるAsciidoctorの優位点 Asciidoctorは継続的にドキュメント開発するための優れた特徴があります。 * 変数が使える。 * includeで文章を分割結合できる。 * if文が使える。 includeでドキュメントを意味のある最小単位に分割して、ビルド時に変数を指定することでDIできます。また、if文と組み合わせることで条件に会わせた表現が可能です。 例えば、Node.JSなどのようにENV=productionとすることで製品リリース用の変数を読み込んで変更なしにリリース版ドキュメントを作成できます。 Asciidoctorを使うことで始めてソフトウェア開発のように継続的に開発できます。 --- 本書でぜひAsciidoctorを使った継続的ドキュメント開発を実践してみてください!

B5 / 54p / PDF / フルカラー Asciidoctorを使って継続的にドキュメント開発するための本です。 1. なぜMarkdownではなくAsciidoctorなのか? Markdownには以下の問題があります。 * 文法の方言が多く、他人の作成したドキュメントの表示が崩れる。 * テーブル表現が弱く、Excelから脱出できない。 Asciidoctorは方言がありません。他人の作成したドキュメントも同じように表示できます。また、行結合などテーブル表現が豊かなのでExcelに近い表現が可能です。 また、MarkdownとAsciidoctorは競合しません。個人メモやWikiなどはMarkdownで良いです。複数人で継続的に開発する場合においてAsciidoctorは効果を発揮します。 2. ドキュメント開発におけるAsciidoctorの優位点 Asciidoctorは継続的にドキュメント開発するための優れた特徴があります。 * 変数が使える。 * includeで文章を分割結合できる。 * if文が使える。 includeでドキュメントを意味のある最小単位に分割して、ビルド時に変数を指定することでDIできます。また、if文と組み合わせることで条件に会わせた表現が可能です。 例えば、Node.JSなどのようにENV=productionとすることで製品リリース用の変数を読み込んで変更なしにリリース版ドキュメントを作成できます。 Asciidoctorを使うことで始めてソフトウェア開発のように継続的に開発できます。 --- 本書でぜひAsciidoctorを使った継続的ドキュメント開発を実践してみてください!