Assignment 2: DITA authoring

Materials:

• Review the presentation at http://www.ditausers.org/tutorials/basics/Priestley_Authoring/
• Read section 3.1 of the DITA 1.1 architectural specification:
  http://docs.oasis-open.org/dita/v1.1/CS01/archspec/archspec.html
• Read the description of <shortdesc> in the DITA 1.1 language specification:
  http://docs.oasis-open.org/dita/v1.1/CS01/langspec/langref/shortdesc.html

Assignment:

• Try signing up for a google alert for all media types for the terms "dita xml" (http://www.google.com/alerts)
• Create a concept, task, and reference topic to support the goal of signing up for a Google alerts for example, a concept explaining the idea, a task describing how to subscribe to an alert, and a reference topic describing the types of alert and options available. You can create more than one topic of each type if you think it's necessary. Follow the guidelines laid out in the presentation.

General comments on Assignment 2

I'd like to give you a sense of what I was looking for in the assignments, and some of the common problems that many people encountered.

I was looking for:

• Appropriately authored shortdescs, based on the guidelines in the DITA 1.1 language specification (link given in the assignment instructions)
• Appropriate use of information type structures, such as properties or tables in reference topic, or steps and prereqs in task.
• Appropriate use of inline markup, such as uicontrol for user interface elements, or xref for links to websites.

Some of the common problems were:

• Missing or inappropriate shortdescs
• Faked headings - a natural impulse coming from HTML, but in XML needs to be addressed with a stylesheet change, not authoring workarounds
• Empty elements - such as leftover stepresult elements with no content.
• Generic highlighting like <b> instead of semantic markup like <uicontrol>

Here's what I suggest going forward:

• Make sure you review the assigned materials. The shortdesc guidelines in particular were crucial for this assignment and I think got overlooked by many. Even if you are already familiar with DITA, the assigned reading/viewing may introduce new concepts or guidelines that are necessary background for the assignment.
• Use the tags-on view to see what kind of DITA markup you're producing, and clean up empty elements etc.
• Review your produced output - if it's not looking/reading like you expected, there may be a problem with the markup.
• Ask questions - now that we have a page up in the dita.xml.org wiki, I'm hoping we can interact with each other more. We have a fair range of experience in the course, which can make it especially intimidating for those new to DITA. But if the more experienced people provide more support through the wiki, that range of experience becomes an asset for everyone.

Attached are the source and output for all the assignments, including my comments. For those reviewing this from outside the course: be kind. This is a big step both for me and for my students, and we're all new to this in different ways. I'm hoping this can be a way to share experiences and see what worked and what didn't, which in an online remote course can be otherwise quite difficult.

Attachment	Size
assignment2-public.zip	279.98 KB