Writing with DITA Topics:

<task>, <concept>, & <reference>

Best practices info drawn from Bellamy et al. (2011).

What we will cover + do:

  • Discuss <task> + class code-review practice
  • Discuss <concept>
  • Discuss <reference>

<task>

What is a <task>?

  • Topic dedicated to procedural information
  • <concept> and <reference> topics support task topics, but are written in different .dita files.

<task> best practices

  • One procedure per topic
  • Create subtasks for longer procedures by creating a "supertask" (Bellamy et al., p. 22)
  • Create <substeps> for longer steps, but don't nest too deep! If so, consider the subtask practice noted above.
  • Combine short, sequential steps within one
    <step>
        <cmd>

<task> best practices, cont'd

  • Every <cmd> should use an imperative sentence and sufficient deixis:
    • Imperatives: Directive / give orders
    • Deixis: Supply contextually-grounded position or placement; think of it as a well-placed gesture
    • WARNING! Use deixis sparingly, especially if you are writing a <stepsection> for reuse in multiple places
  • Use other children elements of <step> to supply more info, when necessary: <info>, <stepresult>, <stempxmp>, <choicetable>, etc.

Example <task> topic file

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE task PUBLIC 
    "-//OASIS//DTD DITA Task//EN"
    "/plugins/org.oasis-open.dita.v1_2/dtd/technicalContent/dtd/task.dtd">

<task id="clear-fix">
  <title>Writing a clear-fix hack</title>
  <shortdesc>
    Write out an overview, benefits, or importance of the task. 
    If necessary, any very brief conceptual information.
  </shortdesc>

  <prolog><metadata>
    <keywords>
      <indexterm>clear-fix</indexterm>
      <indexterm>clear property</indexterm>
      <indexterm>display property</indexterm>
    </keywords>
  </metadata></prolog>

  <taskbody>
      <steps>
        <step id="cf-step">
          <cmd>
            In your CSS file, use the <xref href="c_css_declr_clear.dita">
            <codeph>clear</codeph></xref> declaration inside 
            an <xref href="c_css_pseudo_elem_after.dita"><codeph>
            :after</codeph></xref> pseudo-element on the <codeph>
            .grid</codeph> class to clear <xref href="c_css_val_both.dita">
            <codeph>both</codeph></xref> right and left sides
             of the block.
          </cmd>
          <stepxmp><codeblock>
.grid:after {
  content: "";
  display: table;
  clear: both;
}
          </codeblock></stepxmp>
        </step>
      </steps>

  </taskbody>
</task>

Resources

  • DITA 1.2 spec on the task element
  • Best practice guidelines (Bellamy et al., pp. 39-40).

<--=================
   Code-review time!
   ==============-->

  • Practice code-review together (~10 mins.)

Class Code-Review Practice

<concept>

What is a <concept>?

  • Supports the goals of the task topics
  • Can introduce tools/technology
  • Digs deeper into particular component/property

<concept> best practices

  • One concept per topic
  • Invent conceptual information based on tasks within scoped topic model
  • "Depth" of conceptual information is often contingent on audience's knowledge level
  • Tip: Write the concept with a novice in mind, and use id values to define audience-based content.

<concept> best practices, cont'd

  • Use noun-based phrases for titles
  • Use <section> elements to break-up longer concepts + id attributes to label for reuse purposes
  • Lists can help create scannable content, but limit lists to ~7 items or fewer (p. 45)
  • Use titles for each section
  • Use images or other media to aid your concepts

Example <concept> topic file

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
  "/plugins/org.oasis-open.dita.v1_2/dtd/technicalContent/dtd/concept.dtd">

<concept id="c-float-positioning-scheme">
  <title>CSS float positioning scheme</title>
  <shortdesc>
    Writing CSS involves learning about the different ways you can 
    manipulate the '<xref href="http://www.w3.org/TR/2011/REC-CSS2-20110607/box.html" scope="external" >box model</xref>' 
    and its positioning schemes. One important writing and design 
    method is working with the float positioning scheme.
  </shortdesc>

  <conbody id="c-fps-overview">
    <p>
      According to the CSS Working Group, a float positioning 
      scheme defines the behavior of a box. A box can be "floated" 
      left, right, both, or none within its current position and 
      relation to its parent containing block and other inline 
      elements.
    </p>
    <p>
      For more information about float positioning scheme behavior, 
      see the W3 specification: <xref href="http://www.w3.org/TR/CSS2/visuren.html#floats" scope="external" >http://www.w3.org/TR/CSS2/visuren.html#floats</xref> [outbound link].
    </p>
  </conbody>

</concept>

Tasks + Concepts w/in Scoped Topic Model Structure

css-projects/
  float_grids.ditamap
  understanding_css_grids.ditamap

  grids/
    bootstrap3-grid/
      ... 
    css3-grid-module/
      ...
    flexbox-grid/
      ...

    float-grid/
      topics/
        c_float_grid_overview.dita
        t_coding_grid.dita
      README.md

    purecss-grid/
      ...

    shared-assets/
    shared-topics/
    templates/

  shared-assets/
    web-css-grids.css
  shared-topics/
    c_css_declr_clear.dita
    c_css_float_positioning_scheme.dita
    c_css_pseudo_elem_after.dita
    c_css_val_both.dita
    t_clearfix.dita

Resources

  • DITA 1.2 Spec on the concept element
  • Best practice guidelines (Bellamy et al., p. 50).

<reference>

What is a <reference>?

  • Supports goals of the <task> topics
  • Fills in some gaps related to <concept> topics (Bellamy et al., p. 51)
  • Organizes factual, referential information about things/objects related to the topic model scope

<reference> best practices

  • Use noun-based phrases for titles
  • Write and design for scannability
  • Be consistent about design/elements across topics
  • Difficulty: Modularize reference info or not.
    Rule of thumb: If more than 2 pages, break topic up, logically.
  • All <reference> elements require a <section> element
  • Do not "paper" (p. 60) your reference topics. Avoid writing topics that the user does not need. (Example: UI icons.)

Reference example

Resources