Monthly FAQ for the Debian-user mailing list

[Andrew M.A. Cater]

Debian-user is a mailing list provided for support for Debian users,
and to facilitate discussion on relevant topics.

Some guidelines which may help explain how the list works:

* The language on this mailing list is English. There may be other mailing
lists that are language-specific for example debian-user-french

* It is common for users to be redirected here from other lists - for example,
from debian-project. It is also common for people to be posting here when
English is not their primary language. Please be considerate.

* The list is a Debian communication forum. As such, it is subject to both
the Debian mailing list Code of Conduct and the main Debian Code of Conduct

https://www.debian.org/MailingLists/#codeofconduct
https://www.debian.org/code_of_conduct

* This is a fairly busy mailing list and you may have to wait for an
answer - please be patient. Please post answers back to the list so
others can benefit; private conversations don't benefit people who
may be following along on the list or reading the archives later.

* Help and advice on this list is provided by volunteers in their own time.
It is common for there to be different opinions or answers provided.

* Please try to stay on topic. Arguments for the sake of it are not
welcome here. Partisan political / religious / cultural arguments
do not belong here either. Debian's community is world wide; don't
assume others will agree with your views or need to read them on a
Debian list.

* There is an FAQ on the Debian wiki derived from some questions asked on this
list at https://wiki.debian.org/FAQsFromDebianUser

* One question that comes up on almost all Debian lists from time to time is of
the form:

"I have done something wrong / included personal details in an email.
Could you please delete my name / details / remove the mail"

Practically, this is impossible: the mailing lists are archived, potentially cached
by Google and so on. Unfortunately, there is nothing much we can do to ensure that
all copies anywhere on the Internet are deleted. Asking to do this may only serve to
draw further attention - the so-called "Streisand effect"
See: https://en.wikipedia.org/wiki/Streisand_effect

Problems?
=========

Complaints about inappropriate behaviour should be referred to the
Debian Community Team <comm...@debian.org>.

Inappropriate behaviour on the list may lead to warnings; repeated bad
behaviour may lead to temporary or permanent bans for offenders.

[The Wanderer]

On 2022-10-01 at 05:46, Andrew M.A. Cater wrote:

> Debian-user is a mailing list provided for support for Debian users,
> and to facilitate discussion on relevant topics.
>
> Some guidelines which may help explain how the list works:

Allow me, if you will, to share my experience on receiving each month's
copy of the mailing-list FAQ:

"Oh, there's this month's repost of the FAQ."

"Well, there's no version number or last-changed date or other
information like that, so I can't tell whether or not it's been updated."

"I know I've read the FAQ before, so in the absence of any reason to
think that it may have changed, I'll just assume that it hasn't, and
skip reading it because I probably already know what it says."


By contrast, if the FAQ *did* include an indication of when it was last
updated, I would have one of two lines of reaction. Either:

"Oh, there's this month's repost of the FAQ."

"The version number is the same as last month's / the last-changed date
is more than a month old, so I know I've already read it."

"I'll skip reading it, because I already know what it says."

Or:

"Oh, there's this month's repost of the FAQ."

"Hey, the version number has been increased / I don't know what version
number last month's posting had / the last-changed date is recent, so
there might be information in there that I'm not familiar with."

"I'll read the whole thing, just to be sure I'm up to date on it."



I apply similar reasoning to updated terms-of-service documents, updated
telephone menus ("please listen carefully, as our options have changed",
without any indication of when they changed and so whether there's
anything new since the last time I *did* listen to the whole menu), et
cetera - except that in some of those cases there are immediate or
legally-binding consequences to missing any changes by failing to review
such a document (so I have incentive to shoulder the burden of going
through the document again), whereas with a FAQ such as this there is
not (so I do not).

Including a version number means there's a chance of people with my
mindset - who have read the FAQ before, and don't want to waste time on
reading an unaltered document - reading it again.

Not including one means that such people are guaranteed to not read the
FAQ each time it is reposted - and, therefore, that for such people the
monthly "reminder" copy of the FAQ is a pure waste, and is not achieving
or producing any benefit at all.

I therefore reiterate my suggestion, from what I think was one of the
first times (a previous version of?) this FAQ was (re)posted, that some
versioning information be attached to - and posted along with each copy
of - this FAQ.

--
The Wanderer

The reasonable man adapts himself to the world; the unreasonable one
persists in trying to adapt the world to himself. Therefore all
progress depends on the unreasonable man. -- George Bernard Shaw

[rhkr...@gmail.com]

On Saturday, October 01, 2022 06:10:48 AM The Wanderer wrote:
> On 2022-10-01 at 05:46, Andrew M.A. Cater wrote:
> > Debian-user is a mailing list provided for support for Debian users,
> > and to facilitate discussion on relevant topics.

> I therefore reiterate my suggestion, from what I think was one of the
> first times (a previous version of?) this FAQ was (re)posted, that some
> versioning information be attached to - and posted along with each copy
> of - this FAQ.

+1

And I would expand the suggestion to add "revision marks" (ideally in the left
margin) of the changed sections.

After all, many of us are used to using (word)diff or similar.

(And, this should be done for all legal type documents (changes in terms,
etcs.)

(And, to go one step further, those emails (not from Debian) which say some
list of terms / items has been changed, but without describing the change are
also annoying -- you don't know whether the change might be relevant to you or
not and you have to decide whether to follow the link and then (probably) try
to skim a large part of the document to see what has changed.)

--
rhk

If you reply: snip, snip, and snip again; leave attributions; avoid HTML;
avoid top posting; and keep it "on list". (Oxford comma included at no
charge.) If you change topics, change the Subject: line.

Writing is often meant for others to read and understand (legal agreements
excepted?) -- make it easier for your reader by various means, including
liberal use of whitespace and minimal use of (obscure?) jargon, abbreviations,
acronyms, and references.

If someone else has already responded to a question, decide whether any
response you add will be helpful or not ...

A picture is worth a thousand words -- divide by 10 for each minute of video
(or audio) or create a transcript and edit it to 10% of the original.

[Andrew M.A. Cater]

On Sat, Oct 01, 2022 at 06:10:48AM -0400, The Wanderer wrote:
> On 2022-10-01 at 05:46, Andrew M.A. Cater wrote:
>
> > Debian-user is a mailing list provided for support for Debian users,
> > and to facilitate discussion on relevant topics.
> >
> > Some guidelines which may help explain how the list works:
>
> Allow me, if you will, to share my experience on receiving each month's
> copy of the mailing-list FAQ:
>
> "Oh, there's this month's repost of the FAQ."
>

That's probably a reasonable assumption. It's manually posted by me: it's
the same text, fairly well, each month (modulo any copying error), it's
not currently in version control. Now, I might be prepared to change
that if I were to make any significnt changes.

> "Well, there's no version number or last-changed date or other
> information like that, so I can't tell whether or not it's been updated."
>
> "I know I've read the FAQ before, so in the absence of any reason to
> think that it may have changed, I'll just assume that it hasn't, and
> skip reading it because I probably already know what it says."
>

Also a fair assumption: see above. This is really intended for new readers
- if I do the right thing, it comes early in the month on the first page,
relatively near the top. Anybody reading the list - and I *really* advise
folks to read lists rather than posting in passing - should see it.

>
> By contrast, if the FAQ *did* include an indication of when it was last
> updated, I would have one of two lines of reaction. Either:
>
> "Oh, there's this month's repost of the FAQ."
>
> "The version number is the same as last month's / the last-changed date
> is more than a month old, so I know I've already read it."
>
> "I'll skip reading it, because I already know what it says."
>
> Or:
>
> "Oh, there's this month's repost of the FAQ."
>
> "Hey, the version number has been increased / I don't know what version
> number last month's posting had / the last-changed date is recent, so
> there might be information in there that I'm not familiar with."
>
> "I'll read the whole thing, just to be sure I'm up to date on it."
>

(lots of good reasoning skipped for space)

>
> I therefore reiterate my suggestion, from what I think was one of the
> first times (a previous version of?) this FAQ was (re)posted, that some
> versioning information be attached to - and posted along with each copy
> of - this FAQ.
>

OK, understood.

All best, as ever,

Andy Cater

[Greg Wooledge]

On Sat, Oct 01, 2022 at 02:19:47PM +0000, Andrew M.A. Cater wrote:
> That's probably a reasonable assumption. It's manually posted by me: it's
> the same text, fairly well, each month (modulo any copying error), it's
> not currently in version control. Now, I might be prepared to change
> that if I were to make any significnt changes.

It's not in a file that you simply :r (or equivalent) into the email?
That surprises me.

[The Wanderer]

On 2022-10-01 at 09:44, rhkr...@gmail.com wrote:

> On Saturday, October 01, 2022 06:10:48 AM The Wanderer wrote:
>
>> On 2022-10-01 at 05:46, Andrew M.A. Cater wrote:
>>
>>> Debian-user is a mailing list provided for support for Debian
>>> users, and to facilitate discussion on relevant topics.
>
>> I therefore reiterate my suggestion, from what I think was one of
>> the first times (a previous version of?) this FAQ was (re)posted,
>> that some versioning information be attached to - and posted along
>> with each copy of - this FAQ.
>
> +1
>
> And I would expand the suggestion to add "revision marks" (ideally in
> the left margin) of the changed sections.
>
> After all, many of us are used to using (word)diff or similar.

That's about showing what the changes are (when there are any), which is
an entirely separate and much larger / more-complicated matter.

For example: as soon as you've had more than one change in the entire
history of the document, you need to start considering what the previous
version against which you're showing differences is. If you try to do it
against all of them, it very quickly becomes unwieldy; if you try to do
it against just the previous most recent update, then people have to
track that down to understand what the context of the changes was, and
still need to read the updated document to understand those changes in
full context.

It can still be worth doing - typically against the last formally
published version, preferably with a "commit message" type of notice
along with each such version - for larger documents, EULAs and TOS
notices and privacy policies the like.

But for something like this FAQ, the document is small enough that I
don't mind reading it again when there have been changes, as long as I
don't need to reread it *every time* just *in case there have been
changes*, without any good way to tell whether or not there have (aside
from tracking down the previous posting and comparing for myself).

As such, this request is limited to the specific point of having some
type of versioning attached to the FAQ document. Having a list of "what
changed since the previous version" available somewhere (e.g. in the
header section of the document) might be a nice benefit, but for a
document this short I think it'd probably be overkill.

[Stefan Monnier]

> For example: as soon as you've had more than one change in the entire
> history of the document, you need to start considering what the previous
> version against which you're showing differences is. If you try to do it
> against all of them, it very quickly becomes unwieldy; if you try to do

For me the better option is to point to a version of the file with all
its VCS history so people can see what's been changed when.


Stefan

[The Wanderer]

Yes, but for a tiny and rarely-updated document like this that's even
*more* clearly overkill.

[john doe]

On 10/1/2022 4:19 PM, Andrew M.A. Cater wrote:
> On Sat, Oct 01, 2022 at 06:10:48AM -0400, The Wanderer wrote:
>> On 2022-10-01 at 05:46, Andrew M.A. Cater wrote:
>>
>>> Debian-user is a mailing list provided for support for Debian users,
>>> and to facilitate discussion on relevant topics.
>>>
>>> Some guidelines which may help explain how the list works:
>>
>> Allow me, if you will, to share my experience on receiving each month's
>> copy of the mailing-list FAQ:
>>
>> "Oh, there's this month's repost of the FAQ."
>>
>
> That's probably a reasonable assumption. It's manually posted by me: it's
> the same text, fairly well, each month (modulo any copying error), it's
> not currently in version control. Now, I might be prepared to change
> that if I were to make any significnt changes.
>

I assume that you are a Debian maintainer, to me that is unclear in the
e-mail who you are with regard to Debian and what legitimacy you have to
post this in here!

I have no other comment on the thread itself.

--
John Doe

[debia...@howorth.org.uk]

> On 2022-10-01 at 18:25, Stefan Monnier wrote:
>
> >> For example: as soon as you've had more than one change in the
> >> entire history of the document, you need to start considering what
> >> the previous version against which you're showing differences is.
> >> If you try to do it against all of them, it very quickly becomes
> >> unwieldy; if you try to do
> >
> > For me the better option is to point to a version of the file with
> > all its VCS history so people can see what's been changed when.
>
> Yes, but for a tiny and rarely-updated document like this that's even
> *more* clearly overkill.

If the document were maintained using technology such as a wiki (with
restricted edit permissions) then the wiki underpinnings would maintain
the edit history automatically. A link to the wiki page and a statement
as to whether there were any recent changes would then be sufficient, I
think.

[Pierre-Elliott Bécue]

Andrew is a Debian Developer and member of the Community Team.

Regards,
--
PEB

[rhkr...@gmail.com]

On Sunday, October 02, 2022 05:58:23 AM debia...@howorth.org.uk wrote:
> If the document were maintained using technology such as a wiki (with
> restricted edit permissions) then the wiki underpinnings would maintain
> the edit history automatically. A link to the wiki page and a statement
> as to whether there were any recent changes would then be sufficient, I
> think.

+1

But I would suggest putting a copy of the current text of the wiki page in the
email for convenience of those who don't need the revision history, e.g., first
time readers.

[Charles Curley]

On Sun, 2 Oct 2022 09:08:41 -0400
rhkr...@gmail.com wrote:

> +1
>
> But I would suggest putting a copy of the current text of the wiki
> page in the email for convenience of those who don't need the
> revision history, e.g., first time readers.

Not to pick on rhkr...@gmail.com, I just happened to reply to this
email.

I see a number of suggestions for changes in how the monthly FAQ is
managed. I have yet to see any volunteers to take on the necessary work.

--
Does anybody read signatures any more?

https://charlescurley.com
https://charlescurley.com/blog/