Bug 1213522

Summary:	[doc] Issue in "Configuring an sg_persist resource" - do not use sdX as these are not stable
Product:	[openSUSE] PUBLIC SUSE Linux Enterprise High Availability Extension 15 SP4	Reporter:	Jiri Belka <jiri.belka>
Component:	Documentation	Assignee:	Tahlia Richardson <tahlia.richardson>
Status:	RESOLVED FIXED	QA Contact:	Tanja Roth <taroth>
Severity:	Normal
Priority:	P5 - None	CC:	jiri.belka
Version:	unspecified	Flags:	tahlia.richardson: needinfo?
Target Milestone:	---
Hardware:	Other
OS:	Other
Whiteboard:	https://jira.suse.com/browse/DOCTEAM-1057
Found By:	---	Services Priority:
Business Priority:		Blocker:	---
Marketing QA Status:	---	IT Deployment:	---

Description Jiri Belka 2023-07-20 14:53:57 UTC

Configuring an sg_persist resource:

https://documentation.suse.com/de-de/sle-ha/15-SP4/html/SLE-HA-all/cha-ha-storage-protect.html#sec-ha-storage-protect-sgpersist

Please, never ever use sdX in documentation. See https://www.suse.com/support/kb/doc/?id=000018449 .

Please use grep and change it wherever you can, so our customers do not copy
this bad style. Thank you.

Comment 1 Tahlia Richardson 2023-07-21 04:26:58 UTC

Thank you Jiri, I will do so.

Comment 2 Tahlia Richardson 2023-07-28 04:05:27 UTC

Here's the PR: https://github.com/SUSE/doc-sleha/pull/341

I've made changes where it seemed appropriate, with whatever fit best for that particular section (this meant it was not always the same style for every section).

Let me know if you're happy with these changes.

Comment 3 Jiri Belka 2023-07-28 06:05:55 UTC

(In reply to Tahlia Richardson from comment #2)
> Here's the PR: https://github.com/SUSE/doc-sleha/pull/341
> 
> I've made changes where it seemed appropriate, with whatever fit best for
> that particular section (this meant it was not always the same style for
> every section).
> 
> Let me know if you're happy with these changes.

Hi, as for cacf79916511a82fe6ce2368cec3af5050fd9a6f - the reader will see "/dev/<replaceable>DEVICE_ID</replaceable>" literally?

Comment 4 Tahlia Richardson 2023-07-31 04:47:57 UTC

(In reply to Jiri Belka from comment #3)
> (In reply to Tahlia Richardson from comment #2)
> > Here's the PR: https://github.com/SUSE/doc-sleha/pull/341
> > 
> > I've made changes where it seemed appropriate, with whatever fit best for
> > that particular section (this meant it was not always the same style for
> > every section).
> > 
> > Let me know if you're happy with these changes.
> 
> Hi, as for cacf79916511a82fe6ce2368cec3af5050fd9a6f - the reader will see
> "/dev/<replaceable>DEVICE_ID</replaceable>" literally?

No, the replaceable tags render the text in italics, even in screen output, so the reader will see "/dev/DEVICE_ID".

Comment 5 Jiri Belka 2023-07-31 08:19:38 UTC

(In reply to Tahlia Richardson from comment #4)
> (In reply to Jiri Belka from comment #3)
> > (In reply to Tahlia Richardson from comment #2)
> > > Here's the PR: https://github.com/SUSE/doc-sleha/pull/341
> > > 
> > > I've made changes where it seemed appropriate, with whatever fit best for
> > > that particular section (this meant it was not always the same style for
> > > every section).
> > > 
> > > Let me know if you're happy with these changes.
> > 
> > Hi, as for cacf79916511a82fe6ce2368cec3af5050fd9a6f - the reader will see
> > "/dev/<replaceable>DEVICE_ID</replaceable>" literally?
> 
> No, the replaceable tags render the text in italics, even in screen output,
> so the reader will see "/dev/DEVICE_ID".

IMO, this introduces another confusion - it should be /dev/disk/by-id/<device>.

My 2 cents.

Comment 6 Tahlia Richardson 2023-08-01 04:16:53 UTC

(In reply to Jiri Belka from comment #5)
> (In reply to Tahlia Richardson from comment #4)
> > (In reply to Jiri Belka from comment #3)
> > > (In reply to Tahlia Richardson from comment #2)
> > > > Here's the PR: https://github.com/SUSE/doc-sleha/pull/341
> > > > 
> > > > I've made changes where it seemed appropriate, with whatever fit best for
> > > > that particular section (this meant it was not always the same style for
> > > > every section).
> > > > 
> > > > Let me know if you're happy with these changes.
> > > 
> > > Hi, as for cacf79916511a82fe6ce2368cec3af5050fd9a6f - the reader will see
> > > "/dev/<replaceable>DEVICE_ID</replaceable>" literally?
> > 
> > No, the replaceable tags render the text in italics, even in screen output,
> > so the reader will see "/dev/DEVICE_ID".
> 
> IMO, this introduces another confusion - it should be
> /dev/disk/by-id/<device>.
> 
> My 2 cents.

There are other options like by-uuid and by-partlabel so I was trying not to be prescriptive here, but maybe being prescriptive is better in this case. 

In your experience, is by-id used more than the others? Or if we use by-id, will it be easy logic for the reader to decide to use e.g. by-partlabel instead (I would think so, but we know how some people love to copy without thinking).

Comment 7 Tahlia Richardson 2023-08-08 05:24:36 UTC

(In reply to Tahlia Richardson from comment #6)
> (In reply to Jiri Belka from comment #5)
> > (In reply to Tahlia Richardson from comment #4)
> > > (In reply to Jiri Belka from comment #3)
> > > > (In reply to Tahlia Richardson from comment #2)
> > > > > Here's the PR: https://github.com/SUSE/doc-sleha/pull/341
> > > > > 
> > > > > I've made changes where it seemed appropriate, with whatever fit best for
> > > > > that particular section (this meant it was not always the same style for
> > > > > every section).
> > > > > 
> > > > > Let me know if you're happy with these changes.
> > > > 
> > > > Hi, as for cacf79916511a82fe6ce2368cec3af5050fd9a6f - the reader will see
> > > > "/dev/<replaceable>DEVICE_ID</replaceable>" literally?
> > > 
> > > No, the replaceable tags render the text in italics, even in screen output,
> > > so the reader will see "/dev/DEVICE_ID".
> > 
> > IMO, this introduces another confusion - it should be
> > /dev/disk/by-id/<device>.
> > 
> > My 2 cents.
> 
> There are other options like by-uuid and by-partlabel so I was trying not to
> be prescriptive here, but maybe being prescriptive is better in this case. 
> 
> In your experience, is by-id used more than the others? Or if we use by-id,
> will it be easy logic for the reader to decide to use e.g. by-partlabel
> instead (I would think so, but we know how some people love to copy without
> thinking).

Better? https://github.com/SUSE/doc-sleha/pull/341

Comment 8 Jiri Belka 2023-08-10 08:23:42 UTC

(In reply to Tahlia Richardson from comment #7)

> Better? https://github.com/SUSE/doc-sleha/pull/341

ok for me

Comment 9 Tahlia Richardson 2023-08-11 07:08:11 UTC

This is now completed and backported, and will be published with the next weekly docs update.