Lightweight DITA: Authoring Technical Content in HDITA
26
Lightweight DITA in Action Authoring technical content in HDITA Carlos Evia, PhD @carlosevia
-
Upload
oasis-dita-adoption-tc -
Category
Technology
-
view
25 -
download
0
Transcript of Lightweight DITA: Authoring Technical Content in HDITA
Lightweight DITA in ActionAuthoring technical content in HDITA
Carlos Evia, PhD @carlosevia
About me…• Director of Professional and Technical Writing
• Researcher with the Center for Human-Computer Interaction
• Technical communicator
• Member of the OASIS DITA (Lightweight DITA) committee
Show of hands
• Are you new to DITA?
• Are you a DITA user?
• Are you a DITA expert?
The bloggers are at it again
For people new to DITA• DITA is
• reliable, powerful, customizable, supported, etc.
• HTML5 is
• easy.
For current DITA users and experts
• A new perspective on CCMS
• A new line for the résumé
• Evidence for arguing with the h473r5?
In the beginning… • Michael Priestley
(@ditaguy) proposed
• XDITA
• HDITA
• … and MarkDITA
HDITA• HTML5-based
• Can be used for format and presentation
• Uses data attributes to describe content and not format
<!DOCTYPE html>
Example<article>
<h1>I am a very simple topic</h1>
<p>With my short description</p>
<p>And some content here.</p>
</article>
Task specialization<article data-hd-class="task">
<h1>I am a task</h1>
<p>This is a staging shortdesc</p>
<section data-hd-class="task/steps-informal">
<ol>
<li>Step 1</li>
</ol>
</section>
</article>
My world• I see my students as technical authors in training
• In the tech writing “service course,” some will be full time writers
• But most won’t
• That’s Lightweight DITA’s core audience
Experiment• Modified the
Instructions assignment in a Technical Writing course
• Students did not know DITA XML
• For them, HDITA was DITA.
Research questions
1. How do novice technical writers describe and evaluate the complexity and difficulty of the different stages of the HDITA authoring process?
2. Can novice technical writers author effective topic-based technical content in HTML5 (HDITA) without full knowledge of XML (DITA)?
The process
<!DOCTYPE html>
Assignment
• “You need to write Web-based instructions for a real-life situation. Virginia Tech asked you to develop documentation showing students how to use LibreOffice as an alternative to Microsoft Office or Apple iWork. Your job is to write instructions guiding a first-year college student.”
Participant authors• 18 students
• 12 male and 6 female
• 5 non-native English speakers
• Ages ranged between 19 and 28 years old.
• Academic majors: Mathematics, Computer Science, Electrical Engineering, General Engineering, Biology, Animal and Poultry Sciences, Dairy Science, Environmental Science, Theatre Arts, and Construction Engineering.
Results
• Students said authoring in HDITA was not difficult
• Students said they would use HDITA for future documentation projects
• Students struggled with GitHub Pages, but not with HDITA syntax.
Evaluation27 students from other courses evaluated the deliverables
Qualitycharacteristic
Meanscore Minimumscorereceived
Easytouse 7.26 4
Easytounderstand
7.44 4
Easyto:ind 7.31 3
Demo # 1
• Sample student HDITA code with extra YAML headers and navigation
• Transformed with Jekyll through GitHub Pages.
Is that really DITA?
• Why not…
• Use schema.org?
• Use just Jekyll?
• Use Markdown in GitHub?
Why not?
• Use schema.org?
• Use just Jekyll?
• Use Markdown in GitHub?
Jarno and me
Demo # 2
• Transforming HDITA topics with the DITA Open Toolkit
• We don’t need the YAML headers
• We need the HTML doctype declaration
This is DITA
<h1 class="title topictitle1" id="ariaid-title1">I am a topic</h1>
<div class="body">
<p class="shortdesc">My short description</p>
HDITA offers…• Simplified authoring by using HTML5.
• Instant presentation layer for basic deliverables without transformation.
• Compatibility with XDITA or full DITA XML for advanced processing and filtering.
• Possibility of using a wide variety of commercial and open source editors for HTML5 instead of specialized tools.
• Potential for involving professional communities of Web workers who do not work with XML but are proficient in HTML.
Read more
• Technical Communication article with @ditaguy (February 2016 issue)
• And don’t miss the next session!
