G’day all!
Has consideration been given to how links might be handled from
a high level process to lower level tasks? One handy approach allowed by DITA
is the abstraction of links, where links are derived from the context of the
ditamap collection, rather than be included in the topic.
Troy talked about a model where process items map to task
headings. If a reltable is used to define the links from the process ot the
task, the process will appear to be repeated, with the tasks of the process
first enumerated, and then the reltable links to those tasks generated below. This
might sound a bit oblique, but would it make sense to define a process in the ditamap?
A process might be made up of a concept (overview of process) topic and
then the constituent task topics in sequence.
Tony Self
From: Troy Klukewich
[mailto:troy.klukewich@oracle.com]
Sent: Friday, 14 November 2008 3:46 AM
To: dita@lists.oasis-open.org
Subject: RE: [dita] Revised content model options for #12011 - Generic
Task Type
Hi:
I have some thoughts and observations on the process versus task distinction,
at least from my own history and bias.
On a previous, pre-DITA implementation using structured principles and XML, we
found that there was a clear semantic difference between process and task
descriptions. Basically, in the legacy we found an incredible number of
pseudo-procedures masquerading as tasks, which no one could actually perform on
their own. After the conversion, we made a clear distinction between high level
processes that do no describe discrete, literal steps and tasks, which do.
So, a process might be (off the top of my head):
Creating a database
1. Drop a connection component on the design surface
2. Connect to a data source
3. Configure the data adapter
In the old doc, that would be it. Writers thought they had written a
"task." It looks like a task, right? But when we analyzed the actual
steps involved in this apparently simple process, there were at least 15
discrete steps involved, any one of which would prevent success if not done
properly.
In this particular case, we received numerous support calls because customers
could not in fact build a database application following our old instructions.
When we separated out high level processes from tasks, adding literal steps
where needed, the support calls for this issue vanished.
So, personally, I like to make a hard distinction between processes and tasks.
There is a place for both, but I do not like mixing them together, especially
in a mission critical context. Ideally, all high level processes map to more
detailed tasks, which articulate the actual steps, including case scenarios
with sample data in steps for otherwise abstract, generic processes.
In particular, I like a model where the process items map to task headings to
articulate the step details involved. For more complicated processes that
involve a huge number of steps, there is inevitably a break-out into distinct
sequences, perhaps by screen, object, table, or even an entire application in a
multi-application process. I personally cannot stand gigantic tasks that have
twenty-plus sequential steps. They get tedious to follow and the eye begins to
swim. A process overview is needed in these cases and the steps should be
broken out into related tasks, each heading mapping back to a point in the process
overiew.
Here's the kicker. While I believe that task steps should always be constrained
in a task topic with a specified output, I do not believe that processes should
be constrained to task topics, as I can see a conceptual discussion around high
level processes in conceptual topics as a typical application in enterprise
doc.
On the other hand, complicated tasks may well require a short process overview
in the task itself, assuming that multiple task headings are contained in one
file, which I generally avoid unless the tasks are distinctly related (perhaps
in a case scenario with sample data). This approach is similar to the classic
thesis approach in essay writing where the author would traditionally outline
major points in a preceding paragraph before delving into the (massive) details
within the essay itself. (General to specific.)
While it seems that the process element was created for a number of reasons,
this is how I would implement it myself. I would rather use a process element
than say, an unordered list for a generic process, as there is semantic
relationship to tasks that is worth tracking and keeping separate from the
plethora of other unordered lists that do not describe processes.
Troy Klukewich
Information Architect
Oracle
From JoAnn Hackos
<joann.hackos@comtech-serv.com>
Sent Thu 11/13/2008 5:53 AM
To Bob Thomas <bob.thomas@tagsmiths.com>;
Michael Priestley <mpriestl@ca.ibm.com>
Cc dita@lists.oasis-open.org
Subject RE: [dita] Revised content model options for
#12011 - Generic Task Type
Hi Bob,
I tend to agree with you. I cannot find any rationale in the memos
(so far) for the <process> alternative in task. I can't think of what
it's supposed to handle that cannot already be handled by steps or
steps-unordered. Haven't heard back from Alan Houser, however, who originally
proposed it.
Michael is also checking the email archives.
I'd be in favor of your proposal to chuck it at this point. I think
it just creates confusion for authors.
Regards,
JoAnn
JoAnn
T. Hackos, PhD
President
Comtech Services, Inc.
710 Kipling Street, Suite 400
Denver CO 80215
303-232-7586
joann.hackos@comtech-serv.com
From: Bob
Thomas [mailto:bob.thomas@tagsmiths.com]
Sent: Wednesday, November 12, 2008 1:02 PM
To: JoAnn Hackos; Michael Priestley
Cc: dita@lists.oasis-open.org
Subject: RE: [dita] Revised content model options for #12011 - Generic
Task Type
|
Please pardon my intrusion (I'm a TC observer). I have a
couple of objections to adding 'process' as specified in #12011.
There really needs to be a rationale for this that includes the semantic
intent for 'process'. If allowing 'ol' and 'ul' inside of 'task' is the only
rationale, then you would be better off adding 'section' to 'taskbody'. In
any event, I would rather do neither.
My other objection is a bit more fundamental. In Information Mapping®,
process is considered to be an information type just like concept or task
(procedure). While I do not think that the TC necessarily needs to honor that
distinction, it ought not to lightly dismiss it. The notion of process as an
information type suggests that a section-level implementation of 'process' in
DITA would be inappropriate. If the TC goes ahead and implements 'process',
as proposed in #12011, it would preclude anybody else from creating a
topic-level specialization for process.
In the Information Mapping® compatible DTD that I worked on 10 years ago,
the content model for process was quite similar to the one for procedure
(task); the key difference being that a process had 'stage' elements rather
than 'step' elements.
Regards,
Bob Thomas
President
Tagsmiths, LLC
+1 720 201 8260
--- On Wed, 11/12/08, Michael Priestley <mpriestl@ca.ibm.com>
wrote:
From: Michael Priestley
<mpriestl@ca.ibm.com>
Subject: RE: [dita] Revised content model options for #12011 - Generic Task
Type
To: "JoAnn Hackos" <joann.hackos@comtech-serv.com>
Cc: dita@lists.oasis-open.org
Date: Wednesday, November 12, 2008, 11:00 AM
Hi JoAnn,
The rationale
below is to allow <ol> and <ul> into taskbody. In other words, if
someone wants to create a task with a simple <ol> instead of the more
prescriptive <steps>, the <process> element allows them to do so.
Michael
Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
|
"JoAnn
Hackos" <joann.hackos@comtech-serv.com>
11/12/2008
12:06 PM
|
|
To
|
Michael
Priestley/Toronto/IBM@IBMCA, <dita@lists.oasis-open.org>
|
|
cc
|
|
|
Subject
|
RE:
[dita] Revised content model options for #12011 - Generic Task Type
|
|
Hi
Michael,
The
email from Alan provides no rationale for the <process>, just shows the
syntax. Let me know if any of the minutes show the rationale or any examples.
I’ve written Alan but haven’t received a response as yet.
JoAnn
JoAnn Hackos PhD
President
Comtech Services, Inc.
joann.hackos@comtech-serv.com
Skype joannhackos
From: Michael Priestley
[mailto:mpriestl@ca.ibm.com]
Sent: Tuesday, November 11, 2008 9:22 AM
To: dita@lists.oasis-open.org
Subject: Fw: [dita] Revised content model options for #12011 - Generic
Task Type
Re discussion today about elements in general task - found this, which
provides a bit of background on process - will check meeting minutes from
around this time.
Michael Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
----- Forwarded by Michael Priestley/Toronto/IBM on 11/11/2008 11:21 AM -----
|
Alan
Houser <arh@groupwellesley.com>
12/11/2007
11:01 AM
|
|
To
|
dita@lists.oasis-open.org
|
|
cc
|
|
|
Subject
|
[dita]
Revised content model options for #12011 - Generic Task Type
|
|
I submit this message for possible discussion at today's
(11-December-2007) DITA TC meeting. Below is a summary of proposed
content models that will support proposal #12011 -- Generic Task Type.
These content models are the result of recent discussion on the DITA TC
list.
-Alan
-------------
Summary:
- Optional, repeatable <note> allowed before <cmd>
- <taskbody> allows only a single <steps> element
- New <process> element to permit <ol>/<ul> constructions
in <taskbody>
Proposed content models:
taskbody:
(prereq?,
context?,
(steps | steps-unordered | process),
result?,
example?,
postreq?)
(Issue: allow <section> before and after <steps>?)
steps/steps-unordered:
Support <section> between steps:
(section?, step)+
step:
Support optional, repeatable <note> before cmd:
(note*,
cmd,
(info | substeps | tutorialinfo | stepxmp | choicetable | choices)*,
stepresult?)
Issue: allow <itemgroup> in <step>?
process:
(section?, (ol | ul))+
Issue: this would allow multiple ol/ul elements.
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. You may a link to this group and all your TCs in
OASIS
at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
|
|