bug#57890: 28.1; Doc string of `initial-frame-alist'

[Christopher Dimech]

> Sent: Monday, September 19, 2022 at 4:16 AM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Drew Adams" <drew.adams@oracle.com>
> Cc: 57890@debbugs.gnu.org
> Subject: bug#57890: 28.1; Doc string of `initial-frame-alist'
>
> > From: Drew Adams <drew.adams@oracle.com>
> > CC: "57890@debbugs.gnu.org" <57890@debbugs.gnu.org>
> > Date: Sun, 18 Sep 2022 16:08:03 +0000
> >
> > > > The doc string seems to suggest that the option, or its use, somehow
> > > > depends on X resources:
> > >
> > > And it does.  So I don't understand the complaint.
> >
> > Complaint?
> >
> > It depends on X resources if you have X resources.
> > I'm on MS Windows, for example.  Nothing about X
> > resources is relevant to `initial-frame-list' on
> > that platform, IIUC.
>
> That is incorrect, see the node "MS-Windows Registry" in the Emacs
> user manual (the last paragraph thereof).
>
> > > > That text is not introduced by anything saying, e.g., IF you are
> > > > using X resources or by saying that this 3-step process is
> > > > applicable only if you can use X resources.  At least some of it
> > > > doesn't make sense without X resources, AFAIK.
> > >
> > > Doc strings are not nodes in a manual, they cannot have introductions
> > > and terminology explanations.  They are succinct and assume some level
> > > of general knowledge.

If users are telling you that the information is not helping them, because of
confusion in terminology or certain knowledge, the docstring should certainly
start to say no, so users can be directed on the kind of information they would
likely need to know.

The biggest problem I see, is that at times, too much knowledge is assumed, 
making
the docstring info practically useless.  Docstrings got to become more 
pragmatic.



> > Yes.  And?  This doc string includes platform-specific
> > info without saying that's what it is, no?
>
> It assumes that every user knows enough to understand that.
>
>
> > If you want to make it more succinct, and leave
> > out that X resources info, that's also a way to
> > remedy the confusion.
>
> Yes.  Another effective method is to close this bug.