Re: Monthly FAQ for the Debian-user mailing list
On Sun, 2 Oct 2022 09:08:41 -0400 rhkra...@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 rhkra...@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/
Re: Monthly FAQ for the Debian-user mailing list
On Sunday, October 02, 2022 05:58:23 AM debian-u...@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. -- 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.
Re: Monthly FAQ for the Debian-user mailing list
john doe wrote on 02/10/2022 at 10:38:59+0200: > 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. Andrew is a Debian Developer and member of the Community Team. Regards, -- PEB signature.asc Description: PGP signature
Re: Monthly FAQ for the Debian-user mailing list
> 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.
Re: Monthly FAQ for the Debian-user mailing list
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
Re: Monthly FAQ for the Debian-user mailing list
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. -- 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 signature.asc Description: OpenPGP digital signature
Re: Monthly FAQ for the Debian-user mailing list
> 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
Re: Monthly FAQ for the Debian-user mailing list
On 2022-10-01 at 09:44, rhkra...@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. -- 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 signature.asc Description: OpenPGP digital signature
Re: Monthly FAQ for the Debian-user mailing list
On Sat, Oct 01, 2022 at 02:19:47PM +, 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.
Re: Monthly FAQ for the Debian-user mailing list
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 > -- >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 >
Re: Monthly FAQ for the Debian-user mailing list
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.
Re: Monthly FAQ for the Debian-user mailing list
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
signature.asc
Description: OpenPGP digital signature
