From: Lucas de Sena <lucas@seninha.org>
Subject: Re: www/faq14: make it obvious that file for the new softraid device must have been created
To: Stuart Henderson <stu@spacehopper.org>
Cc: tech@openbsd.org
Date: Mon, 27 Jul 2026 18:11:19 -0300

On 2026-07-27, Stuart Henderson wrote:
>
> On 2026/07/25 15:35, Lucas de Sena wrote:
> > On 2026-07-01, Lucas de Sena wrote:
> > > diff /usr/share/doc/www
> > > path + /usr/share/doc/www
> > > commit - cc2b58cd232efe0f10a698cf8a92796f9690d4b2
> > > blob - cacdc0ceff609c0264bf5e8695023d705bd8d414
> > > file + faq/faq14.html
> > > --- faq/faq14.html
> > > +++ faq/faq14.html
> > > @@ -615,7 +615,9 @@ a master boot record and disklabel, zeroing the first 
> > >  highly recommended.
> > >  Be <b>very careful</b> with this command; issuing it on the wrong device
> > >  could lead to a very bad day.
> > > -This assumes that the new softraid device was created as <code>sd2</code>.
> > > +This assumes that the new softraid device was created as <code>sd2</code>,
> > > +and the special file for <code>sd2</code> have been created by
> > > +<a href="https://man.openbsd.org/MAKEDEV">MAKEDEV(8)</a>.
> > >  
> > >  <pre class="cmdbox">
> > >  # <b>dd if=/dev/zero of=/dev/rsd2c bs=1m count=1</b>
>
> I don't see how this helps. This specifically talks about sd2 which
> _is_ created by the instructions above. If somebody is running into
> problems because they're trying to follow instructions on autopilot
> and don't understand about adapting to having sd3, etc, telling them
> about MAKEDEV again is unlikely to help.

I don't think that those small reinforcements of early information are
an issue in manuals or guides.  Rather, they can be a good thing, if done
moderatedly, for certain details and technicalities, and when in context.

Like internal references and .Sx tags in the manpages, my patch does not
actually tell about MAKEDEV(8) all again; it just reminds of something
told earlier that affects the context in the current paragraph.


On 2026-07-27, Stuart Henderson wrote:
> 
> Maybe something like this?
> 
> -This shows that we now have a new SCSI bus and a new disk, <code>sd2</code>.
> +This shows that we now have a new SCSI bus and a new disk - in this case
> +<code>sd2</code>.
> +If you have additional disk devices, the new disk will be <code>sd3</code>
> +or higher, and following commands will need to be adapted.
>  This volume will be automatically detected and assembled when the system boots.

Seems unnecessary.

The FAQ illustrates a potential setup, which is most probably not the
same to what the reader is dealing with.  Adapting commands to fit the
reader's actual disk setup is an essential part of following the FAQ,
anyway.

I think that remembering the reader that "the device for the softraid
disk (sd2 in this case) must have been made by MAKEDEV" is more useful
than remembering that “the new disk is sd2 here but might be sd3 or
something else for you, and you'll need to adapt the commands”.