http://methodm.com/blog for people who write and edit content everyday Wed, 28 Dec 2011 11:03:01 +0000 http://backend.userland.com/rss092 en Bookmaps enable users to organize their DITA information into front matter, parts, chapters, and back matter. Typically, publications are created from a bookmap while DITA maps are used for simpler documents, or to group topics for reference from a book map or from another DITA map. Group topics in DITA maps http://methodm.com/blog/2011/12/28/the-dita-project-11-book-map-or-dita-map/ The DITA Project #10: Group topics in DITA maps Referring to DITA maps from a book map or from another DITA map provides a great way for grouping topics. Refer to the DITA map in the bookmap whenever you want to include the collection of topics in the bookmap. Tip: You ... http://methodm.com/blog/2011/12/07/the-dita-project-10-group-topics-in-dita-maps/ The best practice, in general, is to reference a DITA map from the &lt;part&gt; element. This allows easy reuse of the collection of topics, and allows editing of the DITA map for the part in parallel to editing of the bookmap. In this example the &lt;chapter&gt; element references a DITA ... http://methodm.com/blog/2011/11/30/the-dita-project-9-nesting-topics-under-a-topic-or-under-a-topichead/ For publications that have two or more very different kinds of information, use &lt;part&gt; to divide a document's chapters into logical groupings. <note type="other" othertype="Example">In a document that contains both procedures and reference information, you can define two parts, one containing the how-to procedures and the other containing ... http://methodm.com/blog/2011/11/24/the-dita-project-8-when-to-use-the-part-element-in-a-bookmap/ Referencing a DITA map from the &lt;chapter&gt; element enables allows easy reuse of the collection of topics in the chapter, and allows editing of the DITA map for the chapter in parallel to editing of the bookmap. In this example the &lt;chapter&gt; element references a DITA map. <codeblock>&lt;chapter href="intro.ditamap" format="ditamap"/&gt;</codeblock> In ... http://methodm.com/blog/2011/11/17/the-dita-project-7-referencing-a-map-or-a-topic-from-the-chapter-element/ Topics, taken alone, are generally just part of larger units of information.  To organize your topics meaningfully, you can: arrange topics into chapters and parts in the bookmap, group topics in DITA maps, and nest child topics under parent topics (sometimes called super topics, super tasks, or chapter maps). nest topics under topic headings In the coming ... http://methodm.com/blog/2011/11/09/the-dita-project-6-organizing-topics/ The DITA Project #4 Polygamous or Monogamous Topics Embedding multiple topics inside one topic file.  Markers for this phenomenon are use of <title> more than once in a topic. The golden rule is one topic, one idea. If you need more than one <title>, with the obvious exception of titles for images or tables, ... http://methodm.com/blog/2011/11/09/the-dita-project-4-polygamous-or-monogamous-topics/ Why use <choices> or <choicetables> instead of <ol> or <ul> in a task topic when you need to choose what to do next? The benefit is that the markup is semantic! When you use <choices> or <choicetables>, the machine (and the writer!) understands explicitly if we are talking about: <choices> where ... http://methodm.com/blog/2011/11/09/the-dita-project-5-choices-or-choicetables/ Writers are conditioned to using tables. Get past it. Table invite endless tampering with settings for column width.  In most cases, get over it and get past it.  Go for <dl>, definition lists. The key point here is "most cases". Most, but not all. If it's absolutely critical that you display content ... http://methodm.com/blog/2010/09/07/the-dita-project-3-definition-lists-or-tables/ To describe a procedure (such as setting up display, removing a panel, etc. ), use a task topic. To describe what you can do, or what options are available, use a reference topic. A good rule of thumb is that users tend to need, and prefer, step-by-step procedures in task topics to ... http://methodm.com/blog/2010/08/26/the-dita-project-2-just-say-no-when-reference-topics-distract/