Topics

notes and tasks

joerg_2712
 

Hy,
can anybody give me a tip?
Sorry, my English ist not the best ;-)

I need a lot of safety notes for use in operating instructions
of machines.
These shall be managing as _topics_ (not as a part of a topic, like
<note>) because they are standardized blocks with a variety of reuse.
They are exported from a special risk management database.
However, these topics must be placed in the context of a task
according to the title and in front of the procedure steps.
They are not part of the prerequesites, because in this context we
describe the operating mode and the position of the components.
Notes are too much different to this contents.

Thanks a lot

Joerg

Michael Priestley
 

Can you give a concrete example of a safety note and a procedure together?

How much content typically goes in these safety notes? EG a paragraph,
several paragraphs...?

I can think of several options, but not sure which ones are appropriate
without a better understanding of the content.

Michael Priestley
mpriestl@...
Dept PRG IBM Canada phone: 416-915-8262
Toronto Information Development




"joerg_2712"
<ferlein@infodok. To: dita-users@...
de> cc:
Subject: [dita-users] notes and tasks
06/22/2004 09:56
AM
Please respond to
dita-users




Hy,
can anybody give me a tip?
Sorry, my English ist not the best ;-)

I need a lot of safety notes for use in operating instructions
of machines.
These shall be managing as _topics_ (not as a part of a topic, like
<note>) because they are standardized blocks with a variety of reuse.
They are exported from a special risk management database.
However, these topics must be placed in the context of a task
according to the title and in front of the procedure steps.
They are not part of the prerequesites, because in this context we
describe the operating mode and the position of the components.
Notes are too much different to this contents.

Thanks a lot

Joerg







Yahoo! Groups Links

joerg_2712
 

Hy Michael,

Can you give a concrete example of a safety note and a procedure
together?

(Still) not in DITA ;-)

Generell structure of safety note (see ANSI Z535):
--------------------------------------------------
- Signal word: Danger/Warning/Caution/Note/Tip
- Safety sign (about 40 different signs):
- safety information: Description of hazards and risks.
- List of the measures for the risk minimization.


Examples of safety notes:
------------------------------------
"Sign"
Warning!
Raised or floating load can lead to severe injuries or serious damage
to property!
- Never go under floating load!
- Keep a sufficiently safe distance away!
- Transport parts as closely as possible over the floor!
- Do not reach below the load when lowering!

"Sign"
Warning!
Severe injuries due to fast rotating cutting set are possible.
- Do not reach into the rotating drive shaft or the cutting set.
- If the safty switch is released, switch off main switch and protect
against unauthorized restarting.
- Open hinged grate and outlet housing only when machine and knife
motor are at a standstill.


My proposal for solution of safety notes
----------------------------------------
Specialized topic <safetynote> only with the structure of <note>
- sign as <image>
- safety information as <p> and <ul>

Publishing in a simple table
+---------+-----------------------------------------+
I empty I signal word dependent from type of note I
+---------+-----------------------------------------+
I sign I safety information I
+---------+-----------------------------------------+


Generell structure of task (my idea):
----------------------------------

See DITA TASK specification with little modifications:
Special section <safety> and existing sections prereq / context /
steps / result / postreq with optional <title>-element.
(Suggestions for improvement in DITA-Standard ???)

Important: Safety notes are placed before the procedure steps!


Example of a task without safety notes (in simplified XML/DITA :-))
-------------------------------------------------------------------
<task>
<preqeq>
Select operation mode ...
Stop the infeeding ...

<context>
image of the machine, bla bla bla

<steps>
<step>Let the machine run with some water ...
<step>Switch off the knife motor.
<step>If necessary: Unscrew outlet pipe.
<step>Clean the outlet pipe with a pipe cleaner ...
</steps>

<result>

<postreq>

</task>


task with links to safety notes in XML
--------------------------------------

<task>

<safety>
Link to safety note
Link to safety note
Link to safety note
...
</safety>

<preqeq>
Select operation mode ...
Stop the infeeding ...

<context>
image of the machine, bla bla bla

<steps>
<result>
<postreq>
</task>


Thanks a lot

Joerg

Michael Priestley
 

Hi Joerg,

If the notes are implemented as separate topics that you link to from the
task:


<safety>
Link to safety note
Link to safety note
Link to safety note
...
</safety>

You may not need a specialization of the taskbody to enable this. DITA
supports the separation of links from the body, into the related-links
section, but they can actually be re-sorted on output and placed wherever.
So rather than specializing taskbody to create a link container, you could
customize the processing for taskbody to pull in the safety links at the
right place.

To summarize:

1) create a specialization for authoring safety notes as separate topics,
as you suggest
2) create an override for task processing that pulls links to safety notes
(based on type) into the appropriate place in the task (either before or
after the shortdesc, your call) on output to HTML
3) also override the processing for related-links, to suppress the safety
note links from processing at the bottom when they appear in a task (or let
them repeat there, if the redundancy is ok)

What do you think? Would this be an appropriate approach?

Michael Priestley
mpriestl@...
Dept PRG IBM Canada phone: 416-915-8262
Toronto Information Development

joerg_2712
 

Hi Michael,

thank you very much for the tips.

You may not need a specialization of the taskbody to enable this.
OK, that's a possibility. However, I think that safety notes are so much important,
that they should be anchored in an special section.

My opinion:
Changing the processing of "related links" is not so nice, because a safety note is
a integrated part of the task. A "related topic" contains additinal but not strong
forcing information for users.

Hyperlinks are the choice for the publishing of related links, but hyperlinks are
very dangerous for the publishing of safety notes.
The different character of the information types is the (my) main reason for the
distinction of related links and safety notes.

I don't understand why this fact isn't implemented in the standard task-definition,
particularly in the USA. The liability and the safety are so much important aspects.
OK, DITA is not specialized but near by the software documentation and the risks are
not so high as the risks in mechanical engineering.

I think, we had to specialize a "d-task" (dangerous task) with a safety-section.

Another reason: Every task can contain real related links, for example to descriptions
of disturbances. If I change the processing of related links, then this applies to all
related links, not for safety notes only. Descriptions as real related links must be placed
after the procedure.

What is your opinion as an experienced technical writer and DITA-architect?

Joerg



Hi Joerg,

If the notes are implemented as separate topics that you link to from the
task:


<safety>
Link to safety note
Link to safety note
Link to safety note
...
</safety>

You may not need a specialization of the taskbody to enable this. DITA
supports the separation of links from the body, into the related-links
section, but they can actually be re-sorted on output and placed wherever.
So rather than specializing taskbody to create a link container, you could
customize the processing for taskbody to pull in the safety links at the
right place.

To summarize:

1) create a specialization for authoring safety notes as separate topics,
as you suggest
2) create an override for task processing that pulls links to safety notes
(based on type) into the appropriate place in the task (either before or
after the shortdesc, your call) on output to HTML
3) also override the processing for related-links, to suppress the safety
note links from processing at the bottom when they appear in a task (or let
them repeat there, if the redundancy is ok)

What do you think? Would this be an appropriate approach?

Michael Priestley
mpriestl@...
Dept PRG IBM Canada phone: 416-915-8262
Toronto Information Development



________________________________________________________________________
________________________________________________________________________



------------------------------------------------------------------------
Yahoo! Groups Links




------------------------------------------------------------------------


Michael Priestley
 

Hi Joerg,


You may not need a specialization of the taskbody to enable this.
OK, that's a possibility. However, I think that safety notes are so much
important,
that they should be anchored in an special section.
I think that's probably true.

My opinion:
Changing the processing of "related links" is not so nice, because a
safety note is
a integrated part of the task. A "related topic" contains additinal but
not strong
forcing information for users.

Hyperlinks are the choice for the publishing of related links, but
hyperlinks are
very dangerous for the publishing of safety notes.
The different character of the information types is the (my) main reason
for the
distinction of related links and safety notes.
It looked to me like your example contained links to safety notes, and that
you were talking about implementing the safety notes as separate topics
that would be linked to from the safety section. Is this not the case?

I don't understand why this fact isn't implemented in the standard
task-definition,
particularly in the USA. The liability and the safety are so much
important aspects.
OK, DITA is not specialized but near by the software documentation and the
risks are
not so high as the risks in mechanical engineering.
I think that's a fair comment. Can you also make it to the dita-tc comments
list? That's the official place to make design suggestions for the base set
of DITA, and I want to make sure it gets on the record.
http://www.oasis-open.org/committees/comments/form.php?wg_abbrev=dita

I think, we had to specialize a "d-task" (dangerous task) with a
safety-section.

I think that's reasonable for now, given the lack of support in the base
task. I'd suggest specializing the prereq section to have two subsections
(could be specialized paragraphs, for example): one for prerequisite
actions, and one for safety. It's a bit of a stretch to say that safety
warnings are a prerequisite, but I think it's defensible, and it gives you
something in the existing task structure to specialize off of.


Another reason: Every task can contain real related links, for example to
descriptions
of disturbances. If I change the processing of related links, then this
applies to all
related links, not for safety notes only. Descriptions as real related
links must be placed
after the procedure.
Placement of related links is a separate issue from inlining their targets.
I think it is legitimate to selectively place related links on output
wherever they make the most sense for the topic. For example, links with
role="ancestor" might become breadcrumb links across the top, and links
with importance="required" might be placed in the prerequisites section of
a task. Overriding the processing would be in two parts: an override for
the place where you want the safety links to appear, and an override of the
existing link processing to ensure that safety links are omitted from the
"related information" section on output. So you wouldn't be moving all
related links to the safety section, only safety note links.

What is your opinion as an experienced technical writer and
DITA-architect?

On the question of inlining safety notes versus linking, inlining probably
makes more sense to me but I don't have much experience with safety and
caution notes. On the question of where to author links, regardless of
placement on output, I've got a strong preference for keeping all links in
the related-links section, and letting the output transform sort them into
their appropriate place on output. That keeps the topic's dependencies all
in one place, where they can be easily supplemented by additional
processes, like the map-based linking we use in IBM. That makes management
of the dependencies easier, for example if the same task has different
warnings depending on where it gets reused.

Michael Priestley
mpriestl@...
Dept PRG IBM Canada phone: 416-915-8262
Toronto Information Development