Bug 841350

Summary:	Apply consistent summary/procedure/result styling to tasks.
Product:	Red Hat Enterprise Virtualization Manager	Reporter:	Stephen Gordon <sgordon>
Component:	Documentation	Assignee:	Stephen Gordon <sgordon>
Status:	CLOSED CURRENTRELEASE	QA Contact:	ecs-bugs
Severity:	unspecified	Docs Contact:
Priority:	unspecified
Version:	3.1.0	CC:	acathrow, dyasny, gklein, jskeoch, yeylon
Target Milestone:	---	Keywords:	Documentation
Target Release:	---
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:	Red_Hat_Enterprise_Virtualization-Installation_Guide-3.1-web-en-US-3.1.0-5.el6eng	Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2012-12-04 17:28:28 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:

Description Stephen Gordon 2012-07-18 18:32:45 UTC

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.

Comment 2 Stephen Gordon 2012-07-18 18:34:04 UTC

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.

Comment 3 Stephen Gordon 2012-08-27 20:32:44 UTC

In theory this is the complete list of topics to be checked/updated:

7341
7517
7519
7520
7521
7522
7523
7524
7525
7526
7527
7528
7529
7530
7531
7532
7533
7534
7535
7536
7537
7538
7539
7540
7609
7610
7611
7612
7613
7614
7615
7616
7617
7618
7619
7620
7621
7622
7623
7624
7625
7626
7627
7628
7629
7630
7631
7632
7633
7634
7635
7636
7637
7638
7639
8410
8411
8412
8413
8434
8435
9420
9941
10007
10008
10030
10031
10231
10232
10233
10234
10235
10236
10731
10732
10733
10777
10782

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.

Comment 4 Stephen Gordon 2012-08-27 20:40:20 UTC

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.

Comment 5 Stephen Gordon 2012-08-28 14:01:16 UTC

I have made an initial sweep of the list, based on my observations:

- These topics are actually references:

  7622
  8410
  8411
  8412
  8413
  8434
  8435

- 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):

  7528
  7529
  7609
  7612
  7616
  7618
  7629
  7636
  10007
  10008

- These topics need major edits or restructuring, in some cases these aren't even correctly marked up as procedures:

  7522
  7523
  7527
  7532
  7611
  7617
  7634

- These are topics no longer in use, at least in the Installation Guide, and should be tagged as such:

  7620
  7626
  7619
  7632
  7638
  7639
  9420

- 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.

Comment 6 Stephen Gordon 2012-08-28 18:05:05 UTC

(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.