SUSE/doc-styleguide

Implement task element?

Opened this issue · 7 comments

There is a suggestion in the Style sheets repo to implement the task element in our style sheets. Its role in the document is similar to that of a sect and it is reportedly relevant for Smart Docs, too.
Shall we adopt it?

Our friendly DocBook designer suggests to make the following children elements of task required ones:
tasksummary and taskprerequisites.

Please see the example (Summary and Requirements):
image

Note: we should also list the usage of this element in DSG

Note: we should also list the usage of this element in DSG

I agree to all that's said above. However, do we want to use this for each and every task in our docs or just where we have a larger task that is broken into subtasks that need to be referred to?

I like the idea. tasksummary makes sense. requirements may not always apply, so I would not make this element mandatory

for me it is still: great to have but I would not make it mandatory

For reference, here is the DocBook element definition from https://tdg.docbook.org/tdg/5.1/task.html

<article xmlns='http://docbook.org/ns/docbook'>
  <title>Example task</title>
  <task>
    <title>Changing a light bulb</title>
    <tasksummary>
      <para>How to change a light bulb</para>
    </tasksummary>
    <taskprerequisites>
      <para>Make sure you have a new light bulb.</para>
      <para>Make sure you have turned off the light switch.</para>
    </taskprerequisites>
    <procedure>
      <step><para>Remove the old light bulb.</para></step>
      <step><para>Insert the new light bulb.</para></step>
      <step><para>Turn on the new light bulb.</para></step>
      <step><para>Throw away the old light bulb.</para></step>
    </procedure>
  </task>

I agree with @jfaltenbacher that taskprerequisites should be optional.

Additionally, I think that we should change Requirements to Prerequisites so that elements and display match.