a more focused YP FAQ?

a more focused YP FAQ?

[Robert P. J. Day]

[-- Attachment #1: Type: text/plain, Size: 2337 bytes --]


  i was perusing the YP ref manual FAQ and i was reminded of the
brilliant foreword from the subversion book by o'reilly, particularly
this part:


"A bad Frequently Asked Questions (FAQ) sheet is one that is composed
not of the questions people actually ask, but of the questions the
FAQ's author wishes people would ask. Perhaps you've seen the type
before:

  Q: How can I use Glorbosoft XYZ to maximize team productivity?

  A: Many of our customers want to know how they can maximize
     productivity through our patented office groupware innovations.
     The answer is simple. First, click on the File menu, scroll down
     to Increase Productivity, then…

"The problem with such FAQs is that they are not, in a literal sense,
FAQs at all. No one ever called the tech support line and asked, “How
can we maximize productivity?” Rather, people asked highly specific
questions, such as “How can we change the calendaring system to send
reminders two days in advance instead of one?” and so on. But it's a
lot easier to make up imaginary Frequently Asked Questions than it is
to discover the real ones. Compiling a true FAQ sheet requires a
sustained, organized effort: over the lifetime of the software,
incoming questions must be tracked, responses monitored, and all
gathered into a coherent, searchable whole that reflects the
collective experience of users in the wild. It calls for the patient,
observant attitude of a field naturalist. No grand hypothesizing, no
visionary pronouncements here—open eyes and accurate note-taking are
what's needed most.

"What I love about this book is that it grew out of just such a
process, and shows it on every page. It is the direct result of the
authors' encounters with users. It began with Ben Collins-Sussman's
observation that people were asking the same basic questions over and
over on the Subversion mailing lists: what are the standard workflows
to use with Subversion? Do branches and tags work the same way as in
other version control systems? How can I find out who made a
particular change?"

  some of the YP FAQ is clearly relevant, while other parts of it seem
to fall into the grey area described above. is it worth spending some
time canvassing people and collecting truly Frequently Asked
Questions?

rday

Re: [docs] a more focused YP FAQ?

[Richard Purdie]

On Sat, 2021-05-29 at 07:18 -0400, Robert P. J. Day wrote:
>   i was perusing the YP ref manual FAQ and i was reminded of the
> brilliant foreword from the subversion book by o'reilly, particularly
> this part:
> 
> 
> "A bad Frequently Asked Questions (FAQ) sheet is one that is composed
> not of the questions people actually ask, but of the questions the
> FAQ's author wishes people would ask. Perhaps you've seen the type
> before:
> 
>   Q: How can I use Glorbosoft XYZ to maximize team productivity?
> 
>   A: Many of our customers want to know how they can maximize
>      productivity through our patented office groupware innovations.
>      The answer is simple. First, click on the File menu, scroll down
>      to Increase Productivity, then…
> 
> "The problem with such FAQs is that they are not, in a literal sense,
> FAQs at all. No one ever called the tech support line and asked, “How
> can we maximize productivity?” Rather, people asked highly specific
> questions, such as “How can we change the calendaring system to send
> reminders two days in advance instead of one?” and so on. But it's a
> lot easier to make up imaginary Frequently Asked Questions than it is
> to discover the real ones. Compiling a true FAQ sheet requires a
> sustained, organized effort: over the lifetime of the software,
> incoming questions must be tracked, responses monitored, and all
> gathered into a coherent, searchable whole that reflects the
> collective experience of users in the wild. It calls for the patient,
> observant attitude of a field naturalist. No grand hypothesizing, no
> visionary pronouncements here—open eyes and accurate note-taking are
> what's needed most.
> 
> "What I love about this book is that it grew out of just such a
> process, and shows it on every page. It is the direct result of the
> authors' encounters with users. It began with Ben Collins-Sussman's
> observation that people were asking the same basic questions over and
> over on the Subversion mailing lists: what are the standard workflows
> to use with Subversion? Do branches and tags work the same way as in
> other version control systems? How can I find out who made a
> particular change?"
> 
>   some of the YP FAQ is clearly relevant, while other parts of it seem
> to fall into the grey area described above. is it worth spending some
> time canvassing people and collecting truly Frequently Asked
> Questions?

Many of the questions there have been there for a long time. Some were 
generated by answering questions asked by people on the irc channel.

The trouble is the world moves on and changes and not many new ones
have been added in a long time. We'd very much welcome new entries 
for there (and removal of anything which is now too old/obscure if
appropriate).

If anyone has the time and wants to figure out new entries, please do!

Cheers,

Richard