Zenn
Open9

LwDITA本のラフスケッチ

Markdown
XML
#
dita
hidarumahidaruma

Notation

執筆中のLwDITA本について、進みが悪いのでとりあえずラフで書いてから正式版にしていくことにした。
順序などがばらける。

hidarumahidaruma

LwDITAのSpecificationについて

LwDITAは「従来のDITAが複雑すぎて新規に学ぶには辛いのでは」といったモチベで策定され中。
DITAのサブセットとして使えるようになる（DITA-OTで現行の実装は試せる）。現在のSpecificationはドラフト版。
DITA 2.0と協調しながら現在も策定中らしいので、1.3での半端な状況からちゃんとしたサブセットになるのでは。

ただこのSpecificationの書き方は「fullDITAのうちこれが使えるよ」といった視点で書かれているので、「LwDITAからならDITAを始められる！」という人にはそこそこ辛い。辛かったです。

日本語資料が自分が書いたものくらいしかない。

hidarumahidaruma

LwDITAの資料がないわけではない

  • 策定の中心メンバーであるCarlos Evia氏が執筆した"CREATING INTELLIGENT CONTENT WITH LIGHTWEIGHT DITA"は実例などを交えながら書かれている。ただし英語版しかない。
  • GitHub上にLwDITAでLwDITAについてドキュメントを書いているリポジトリがある。ただし英語版しかない。
  • LwDITAの最新情報はOASISのDITAのLwDITAサブコミッティの議事録、GitHubのLwDITAリポジトリがある。メインブランチは停滞していて、議事録の結果を反映したspecのブランチがある。ただし英語版しか

自分で書いた資料は今回は自分の参考にはならないので割愛。

hidarumahidaruma

執筆する本のターゲット

  • DITAを始めるためにLwDITAを始める人
    • これが本来のターゲットだがニッチすぎるのでもう少し広げる
  • トピック指向での文書の書き方を学び始める人
    • 「理系の文章術～」「テクニカルドキュメント」「実用的文書」といった題ではよく書かれるテーマであるが、この題で苦手意識を持ってしまう人にアプローチできるとより良い
  • 自身は書けるが他の人に伝えるのができない人が薦められる本
    • まあ理想目標
hidarumahidaruma

LwDITA本はDITAで書いていない

  • 慣れてしまうと直XML書きはあんまり抵抗ない
  • 技術書を書く場合、LwDITAだと索引語（indexterm）が使えないのが辛い
  • 相互参照の際、MDITAのパーツに参照を付けるのは難しい
  • LwDITAで対応していない語彙を使いたいケース
    • fig/titleが使えないのが辛い
    • codeblockがない。preのみ。coderefもない
    • XMLに言及するのでxmlelementなどがあった方が結果的にやりやすい
  • DITA-OTのLwDITAプラグインではセクションタイトルが日本語のとき、変換時に@idに日本語をつっこんでくる（多分誤りではないが）
hidarumahidaruma

related-links:

LwDITA本のシナリオ

<ol>
<li><p><xref keyref="ref.book.part.structure" >文書とテキストの構造</xref>
<ol>
<li><p>パラグラフライティング</p></li>
<li><p>メール・チケット・トピック指向ライティング</p></li>
<li><p>構造の物理的表現</p></li>
<li><p>MarkupとMarkdown</p></li>
</ol>
</p>
</li>
<li><p>LwDITA Introduction
<ol>
<li><p>DITA・LwDITAの概要</p></li>
<li><p>MDITA入門 テキストを書く</p></li>
<li><p>HDITA入門 MDITAで書けるものと書けないもの</p></li>
<li><p>MDITAでも再利用がしたい Extended Profile</p></li>
<li><p>XDITA入門</p></li>
<li><p>Map入門</p></li>
<li><p>DITA-OTの導入</p></li>
</ol>
</p>
</li>
<li>
<p>LwDITAで始めるDITA入門
<ol>
<li><p>スキーマを読もう</p></li>
<li><p>特殊化・一般化</p></li>
</ol>
</p>
</li>
</ol>

hidarumahidaruma

トピックがLwDITAでも、DITAMAP側でtopicmetaをがっつり書けばindexは実現できる？

hidarumahidaruma

再構成目次。DITA-OTがmditamap対応したのと、normalize DITAでないDITA化の目処もたったし、まずMDITAで書いて変換するやつにチャレンジしようかと思う。Zenn上ではリンクは

---
lang: ja
id: book.lw
---
# Lightweight DITAで始めるDITA入門 大規模マニュアル作成エコシステムに学ぶドキュメント作成と管理

* [序 DITAの課題とLwDITA]()
* [表現方法を中心に学ぶテクニカルライティングの基本](intro_document/intro_document.md)
  * []()
    * [項目の粒度とトピック]()
    * [ラベル-コンテンツモデルによる構造整理の概要]()
  * [なぜMarkdownを使うのか ドキュメントの統制の第一歩](intro_document/about_md.md)
  * [セクショニング 見出しとブロック]()
  * [ブロック]()
    * [段落]()
    * [リスト]()
    * [表（テーブル）]
  * [文中（インライン）表現]
    * [強調・強勢]
    * [参照]
    * [画像]
    * [註（脚註）]
  * [管理用情報の付記（メタデータ）]()
  * [補足 実際に於ける表現方法の優先順位付け]()
* [MDITAでドキュメントを執筆する]()
  * [単体のトピック]
  * [マップ 複数のトピックをまとめてドキュメントにする]()
  * [DITA Open toolKitでドキュメントをパブリッシュする]()
  * [足りない構造をExtend Profileで補う]()
    * [コラム欄を書く]()
  * [使い回し・改版耐性を上げる再利用機構]()
* [マークアップなLightweight DITA]()
  * [軽量化DITAのXDITA]()
  * [HTMLのすがた HDITA]()
  * [執筆に於ける統制 スキーマ検証]()
    * [DITAの標準トピック型]
    * [標準（Normal）構造と独自（Specialized）構造の判断]
    * [Next Step: Schematron]()
  * [XDITAで学ぶ、DITAのモジュラーDTD構成]()
  * [LwDITA to DITAマイグレーション]()
    * [Normalize DITA]()
    * [DITA-OTに独自プラグインを追加する]()
* [大規模ドキュメントの管理方法]
  * [なぜCCMSが必要になるのかとその緩和策 DITA for Small Team]()
  * [バージョン管理システムとクラウドサービス]()
  * [CI/CD]()
* [DITAとLwDITAのアーキテクチャ]()
* [補足]()
  * [Apache FOPの日本語まわリ]()
  * [Visual Studio CodeとXMLエディタ]()