Red Hat Bugzilla – Bug 841350
Apply consistent summary/procedure/result styling to tasks.
Last modified: 2014-03-25 03:13:03 EDT
Description of problem:
In 3.0, as part of our initial testing of topic-based authoring, we made some changes to the way we format procedures - by adding an explicit 'Result'.
For 3.1 there is a new procedure template that expands on this, as well as the 'Result' it provides a 'Summary' up front. This template was created primarily for the Admin Guide rewrite but given:
- It lines up with the direction the Install Guide procedures were heading anyway.
- The amount of crossover in content between the two guides (meaning procedures written for one invariably show up in the other).
I think the same template should be used for install guide topics. For beta 1 we are probably going to be a little inconsistent here, I'd like to deliver upon this for a later beta and/or GA.
Additional goal here is to replace Tasks that currently make use of a lot of nesting (via substeps and stepalternatives) with a number of atomic Tasks which are chained together in the new 'Process' container.
In theory this is the complete list of topics to be checked/updated:
I'm not sure that updating all of these in one hit will be feasible without killing translation. First step though is to go through the list and see how many already fit the format and/or are close enough that only minor edits are required.
Initial inspection of a handful of these indicates that most already have a summary and result paragraph which wont need editing (and thus wont cause re-translation), they just need the appropriate headings added.
I have made an initial sweep of the list, based on my observations:
- These topics are actually references:
- These topics need minor edits to get them into the desired shape. For most this means they had either an summary or result paragraph that just needs to the correct mark up but were missing the other (so it needs to be written):
- These topics need major edits or restructuring, in some cases these aren't even correctly marked up as procedures:
- These are topics no longer in use, at least in the Installation Guide, and should be tagged as such:
- The remaining topics were either already in the correct format or required minor editing to get them into it. Generally this means that both summary and result paragraphs already existed and they just needed to be marked up as <formalpara>. The procedure titles also needed to be added in some cases.
(In reply to comment #5)
> - These topics are actually references:
These have been updated and are now marked as such,
> - These topics need minor edits to get them into the desired shape. For most
> this means they had either an summary or result paragraph that just needs to
> the correct mark up but were missing the other (so it needs to be written):
These edits have been made.
> - These topics need major edits or restructuring, in some cases these aren't
> even correctly marked up as procedures:
These edits have been made, with the exception of 7634 which I realised is no longer required.
> - These are topics no longer in use, at least in the Installation Guide, and
> should be tagged as such:
The RHEV Installation Guide tag has been removed from these.