← Prev in month
← Prev in thread
Sample use case for the template-based specialization discussion
Per discussion at the close of today's meeting:
Here is a potential use case that currently derives from DITA 1.1
topic, so I present it as a study for deriving from Lightweight
DITA topic. It is very simple, and happens to be oriented around
section-level examples plus a specialized title. This example
exactly supports the data model used in XML Press's "The Language
of Content Strategy" wiki. I am now using this template for an
expeDITA-based wiki that might replace that Confluence tool.
The user story is that invited authors are given a term to
document. When they log into the wiki they find the base topic
already set up by admins. The outputclass in that topic drives an
editor that shows only the key fields they need to edit. Those
fields are represented by the specialized class definitions
(although we discussed adding the name into a fixed outputclass
value so that tools can get the value without parsing). Reviewers
may have access to the full document in a regular editor so that
they can add indexterms and repair inline markup that might have
semantic intent for the publishing transforms. The tlotermtopic
and tlotermbody elements do not need to set up their own form, but
they are required to enable having specialized content.
<!ATTLIST tlotermtopic class CDATA "- topic/topic
tloterm/tlotermtopic ">
<!ATTLIST tloterm class CDATA "- topic/title
tloterm/tloterm ">
<!ATTLIST tlotermbody class CDATA "- topic/body
tloterm/tlotermbody ">
<!ATTLIST tlowhat class CDATA "- topic/section
tloterm/tlowhat ">
<!ATTLIST tlowhy class CDATA "- topic/section
tloterm/tlowhy ">
<!ATTLIST tloessay class CDATA "- topic/section
tloterm/tloessay ">
<!ATTLIST tlosummary class CDATA "- topic/section
tloterm/tlosummary ">
A form set up for these fields might look like this:
<form action="" method="post">
<fieldset>
<label>Term:</label>
<input name="tloterm" type="text"
placeholder="Term"/>{value}<br />
<label>What is it?</label>
<textarea
name="tlowhat">{value}</textarea><br />
<label>Why is it important?</label>
<textarea
name="tlowhy">{value}</textarea><br />
<label>Why does an information developer need to
know this?</label>
<textarea name="tloessay"
class="WYSIWYG">{value}</textarea><br />
<label>Summary?</label>
<textarea name="tlosummary"
class="WYSIWYG">{value}</textarea><br />
<input type="hidden" name="processme"
value="yes"/>
<input type="submit" value="Update"/><br
/>
</fieldset>
</form>
And the requisite sample:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE tlotermtopic PUBLIC "-//LbyW//DTD DITA TLO Term
Topic//EN"
"../../../../../DITA-OT/dtd/plugins/tlotc/tlotermtopic_shell.dtd">
<tlotermtopic id="termdef_term">
<tloterm>Structured Content</tloterm>
<prolog>
<author type="creator">Don Day</author>
<critdates>
<created date="2014-02-23"/>
</critdates>
<metadata>
<category>design</category>
<keywords>
<indexterm props="role(author)">Day,
Don</indexterm>
<indexterm props="role(subject)">structured
content<indexterm>defined</indexterm></indexterm>
<indexterm
props="role(subject)">content<indexterm>structured</indexterm></indexterm>
</keywords>
<othermeta name="date_assigned" content="Jun 13,
2013"/>
<othermeta name="status" content="published"/>
</metadata>
</prolog>
<tlotermbody>
<tlowhat>
<p>Content, whether in a textual, visual, or
playable format, that conforms to structural and semantic rules
that allow machine processing to meet specific business
requirements.</p>
</tlowhat>
<tlowhy>
<p>Humans are much better than computers when it
comes to understanding the nuances of content. Structuring content
with semantic metadata allows computers to understand the
content’s relationship to business processes. This enables better
discovery, marketing, and user engagement.</p>
</tlowhy>
<tloessay>
<p>Readers understand the visual grammar of
style in what they read in a browser or in print, but computers do
not. Even for scanned pages converted into word processor files,
the computer can only determine that something in a block of text
is possibly a paragraph, but it cannot necessarily discern a
paragraph from a note or a quotation. By indicating the order and
intent of the parts of a document, writers ensure that publishing
tools well into the future can usefully render that content, even
if reading technologies change.</p>
<p>Adding structure to content adds both present
and future value, turning content from a single-use commodity into
a long-term asset. Content can be structured in a number of ways,
although most commonly it is done by applying descriptive,
codified markup to it (Extensible Markup Language (XML) or other
semantic markup) or by storing content in named fields in a
database.</p>
<p>Structured content clearly indicates not only
the parts of the discourse (the titles, sections, lists, tables,
and phrases that represent organization) but also the semantic
intent of those containers. For example, paragraphs identified
more specifically as quotations can be not only rendered
differently for readers, but also made more easily discovered in
searches for quotations or citations.</p>
</tloessay>
<tlosummary>
By structuring content appropriately, you can more easily
turn information into knowledge, instructions into automation,
concepts into lesson units, and more, thereby increasing its value
to the business.
</tlosummary>
</tlotermbody>
</tlotermtopic>
And it renders thus (indeed, a more user-friendly,
contentEditable-based editor might actually mimic this styling):
Structured Content
What
is it?
Content,
whether in a textual, visual, or playable format, that
conforms to structural and semantic rules that allow
machine processing to meet specific business requirements.
Why
is it important?
Humans
are much better than computers when it comes to
understanding the nuances of content. Structuring content
with semantic metadata allows computers to understand the
content’s relationship to business processes. This enables
better discovery, marketing, and user engagement.
Why
does a technical writer need to know this?
Readers
understand the visual grammar of style in what they read
in a browser or in print, but computers do not. Even for
scanned pages converted into word processor files, the
computer can only determine that something in a block of
text is possibly a paragraph, but it cannot necessarily
discern a paragraph from a note or a quotation. By
indicating the order and intent of the parts of a
document, writers ensure that publishing tools well into
the future can usefully render that content, even if
reading technologies change.
Adding
structure to content adds both present and future value,
turning content from a single-use commodity into a
long-term asset. Content can be structured in a number of
ways, although most commonly it is done by applying
descriptive, codified markup to it (Extensible Markup
Language (XML) or other semantic markup) or by storing
content in named fields in a database.
Structured
content clearly indicates not only the parts of the
discourse (the titles, sections, lists, tables, and
phrases that represent organization) but also the semantic
intent of those containers. For example, paragraphs
identified more specifically as quotations can be not only
rendered differently for readers, but also made more
easily discovered in searches for quotations or citations.
Summary
By
structuring content appropriately, you can more easily turn
information into knowledge, instructions into automation,
concepts into lesson units, and more, thereby increasing its
value to the business.
--
Don
On 7/27/2015 9:36 AM, Michael
Priestley wrote:
I meant this:
https://lists.oasis-open.org/archives/dita-lightweight-dita/201507/msg00001.html
Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
http://dita.xml.org/blog/michael-priestley
From: "Don R. Day" <>
To:
Date: 07/27/2015 10:31 AM
Subject:
Re:
[dita-lightweight-dita] Agenda for today's lightweight DITA
mtg
Sent by:
<>
Re. the 'approach to specialization' email, do
you mean this?
https://lists.oasis-open.org/archives/dita-lightweight-dita/201505/msg00032.html
--
Don
On 7/27/2015 8:49 AM, Michael Priestley wrote:
We'll review status of domain
investigations, talk about the updated topic and map DTDs Mark
has provided, and then discuss the approach to specialization
using specialized data elements that I sent out in a previous
email.
Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
http://dita.xml.org/blog/michael-priestley
--
Don R. Day
Founding Chair, OASIS DITA Technical Committee
LinkedIn: donrday Twitter:
@donrday
About.me: Don
R.
Day Skype:
don.r.day
"Where is the wisdom we have lost in
knowledge?
Where is the knowledge we have lost in information?"
--T.S. Eliot
This email has been
checked for viruses by Avast antivirus software.
www.avast.com
--
Don R. Day
Founding Chair, OASIS
DITA Technical Committee
LinkedIn: donrday Twitter:
@donrday
About.me: Don R. Day Skype:
don.r.day
"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
--T.S. Eliot
This email has been checked for viruses by Avast antivirus software.
www.avast.com
Attachment:
tlotc.zip
Description: Zip compressed data
← Prev in month
← Prev in thread