Open8

LwDITA本のラフスケッチ

Notation

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

LwDITAのSpecificationについて

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

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

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

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

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

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

構造的な文章と構造化文書

//TODO

執筆する本のターゲット

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

LwDITA本はDITAで書いていない

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

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>

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

ログインするとコメントできます