Re: www/faq14: make it obvious that file for the new softraid device must have been created

On 2026/07/27 18:11, Lucas de Sena wrote:
> 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”.

If someone forgot MAKEDEV there's not really an issue, they can just
read through again and fix it. Though tey were already told to run
MAKEDEV so why would they not have run it already at that point?
Seems only really likely if they didn't create the correct device
node.

If someone forgot that the new softraid drive might not be sd2 before
they scribble over the start of it then that is potentially quite a big
issue...