Обсуждение: 5 new entries for FAQ

Поиск
Список
Период
Сортировка

5 new entries for FAQ

От
Martijn van Oosterhout
Дата:
Hi,

After going through pgsql-general a bit I figured there were a few
important questions missing from the FAQ, so I wrote some.

Comments welcome. I can write more, if people can suggest things to
write about. I was thinking something about collation and locales but
I'm sure sure I understand them myself.

Have a nice day,
--
Martijn van Oosterhout   <kleptog@svana.org>   http://svana.org/kleptog/
> Patent. n. Genius is 5% inspiration and 95% perspiration. A patent is a
> tool for doing 5% of the work and then sitting around waiting for someone
> else to do the other 95% so you can sue them.

Вложения

Re: 5 new entries for FAQ

От
Brendan Jurd
Дата:
> Comments welcome. I can write more, if people can suggest things to
> write about. I was thinking something about collation and locales but
> I'm sure sure I understand them myself.
>

The following should read "... has no facility to fire jobs ..."

+    <P>PostgreSQL itself has no facility fire jobs off at regular intervals,
+    it is recommended to use the operating system to handle this. For UNIX
+    systems this generally means <SMALL>cron</SMALL>, for Windows systems it
+    may mean the Task Scheduler.

--
BJ

Re: 5 new entries for FAQ

От
Brendan Jurd
Дата:
> Comments welcome. I can write more, if people can suggest things to
> write about. I was thinking something about collation and locales but
> I'm sure sure I understand them myself.
>

Missed this on the first pass, but you need to s/seperate/separate here:

+    <P>A seperate project has started with the goal to create a job
+    scheduler for PostgreSQL, see

--
BJ

Re: 5 new entries for FAQ

От
Roman Neuhauser
Дата:
# kleptog@svana.org / 2005-08-10 10:02:20 +0200:
> After going through pgsql-general a bit I figured there were a few
> important questions missing from the FAQ, so I wrote some.
>
> Comments welcome. I can write more, if people can suggest things to
> write about. I was thinking something about collation and locales but
> I'm sure sure I understand them myself.

> +    <H3><A name="4.22">4.22</A>) Why are PostgreSQL table names case-sensitive?</H3>

    http://www.postgresql.org/docs/current/static/features.html doesn't
    contain "fold" (as in "case folding") at all, doesn't this topic
    belong rather there? The FAQ entry could point to, and maybe extend,
    the (still nonexistent) text in that document.

> +    <H3><A name="4.23">4.23</A>) Why is PostgreSQL only using one CPU to execute my query?</H3>

    Something like this is missing from
    http://www.postgresql.org/docs/current/static/overview.html.

> +    <H3><A name="4.25">4.25</A>) What does 'index row size ... exceeds btree maximum, 2713' mean?</H3>
> +
> +    <P>Unlike some databases, PostgreSQL allows you to create an index on
> +    any column, including unlimited text fields. However, B-Tree indexes
> +    need to be able to hold at least three key values per page and since the
> +    pagesize defaults to 8K minus some overhead, this means the maximum key
> +    size is 2713 bytes.

    This is missing from
    http://www.postgresql.org/docs/current/static/sql-createindex.html
    and/or http://www.postgresql.org/docs/current/static/indexes.html

--
How many Vietnam vets does it take to screw in a light bulb?
You don't know, man.  You don't KNOW.
Cause you weren't THERE.             http://bash.org/?255991

Re: 5 new entries for FAQ

От
Martijn van Oosterhout
Дата:
On Wed, Aug 10, 2005 at 10:44:14AM +0200, Roman Neuhauser wrote:
> > +    <H3><A name="4.22">4.22</A>) Why are PostgreSQL table names case-sensitive?</H3>
>
>     http://www.postgresql.org/docs/current/static/features.html doesn't
>     contain "fold" (as in "case folding") at all, doesn't this topic
>     belong rather there? The FAQ entry could point to, and maybe extend,
>     the (still nonexistent) text in that document.

Well, it's not a feature, so I'm not sure why it would be mentioned
there. It's PostgreSQL's implementation of the standard. It is all
explained it detail in:

http://www.postgresql.org/docs/8.0/static/sql-syntax.html#SQL-SYNTAX-IDENTIFIERS

It's just that the question as stated comes up regularly and in this
form, which is why I did that. Perhaps a link would be a good idea.

> > +    <H3><A name="4.23">4.23</A>) Why is PostgreSQL only using one CPU to execute my query?</H3>
>
>     Something like this is missing from
>     http://www.postgresql.org/docs/current/static/overview.html.

Again, the necessary information is in:

http://www.postgresql.org/docs/8.0/static/connect-estab.html

But if they don't read that bit or don't understand the consequences of
it they're going to come asking a question like the way I wrote it. I
think it would be a footnote in that section of the docs.

> > +    <H3><A name="4.25">4.25</A>) What does 'index row size ... exceeds btree maximum, 2713' mean?</H3>
> > +
> > +    <P>Unlike some databases, PostgreSQL allows you to create an index on
> > +    any column, including unlimited text fields. However, B-Tree indexes
> > +    need to be able to hold at least three key values per page and since the
> > +    pagesize defaults to 8K minus some overhead, this means the maximum key
> > +    size is 2713 bytes.
>
>     This is missing from
>     http://www.postgresql.org/docs/current/static/sql-createindex.html
>     and/or http://www.postgresql.org/docs/current/static/indexes.html

Well, I don't see it in the docs, maybe I missed it. It should at the
very least be in the FAQ. Not sure where else it should go...

Have a nice day,
--
Martijn van Oosterhout   <kleptog@svana.org>   http://svana.org/kleptog/
> Patent. n. Genius is 5% inspiration and 95% perspiration. A patent is a
> tool for doing 5% of the work and then sitting around waiting for someone
> else to do the other 95% so you can sue them.

Вложения

Re: 5 new entries for FAQ

От
Roman Neuhauser
Дата:
# kleptog@svana.org / 2005-08-10 11:22:16 +0200:
> On Wed, Aug 10, 2005 at 10:44:14AM +0200, Roman Neuhauser wrote:
> > > +    <H3><A name="4.22">4.22</A>) Why are PostgreSQL table names case-sensitive?</H3>
> >
> >     http://www.postgresql.org/docs/current/static/features.html doesn't
> >     contain "fold" (as in "case folding") at all, doesn't this topic
> >     belong rather there? The FAQ entry could point to, and maybe extend,
> >     the (still nonexistent) text in that document.
>
> Well, it's not a feature, so I'm not sure why it would be mentioned
> there. It's PostgreSQL's implementation of the standard.

    That page has this heading: "Appendix D. SQL Conformance"

> It is all explained it detail in:
>
> http://www.postgresql.org/docs/8.0/static/sql-syntax.html#SQL-SYNTAX-IDENTIFIERS

    Seeing as the last para in 4.1.1. Identifiers and Key Words seems to
    be almost exactly what you came up with (not accusing you of
    "plagiarism" or such, the wording is obvious, and different people
    will arrive at virtually identical explanations), wouldn't just
    linking there suffice? (I'm a bit worried about information scatter
    and duplication).

> It's just that the question as stated comes up regularly and in this
> form, which is why I did that. Perhaps a link would be a good idea.

    Yes, that question is quite common, and perfectly answered in the
    documentation; I would just point at it from the FAQ.

--
How many Vietnam vets does it take to screw in a light bulb?
You don't know, man.  You don't KNOW.
Cause you weren't THERE.             http://bash.org/?255991

Re: 5 new entries for FAQ

От
Martijn van Oosterhout
Дата:
On Wed, Aug 10, 2005 at 07:40:23PM +0200, Roman Neuhauser wrote:
> # kleptog@svana.org / 2005-08-10 11:22:16 +0200:
> > Well, it's not a feature, so I'm not sure why it would be mentioned
> > there. It's PostgreSQL's implementation of the standard.
>
>     That page has this heading: "Appendix D. SQL Conformance"

Ah, well, I'm not going to comment on what should or shouldn't be on
that page. I've never seen nor read the standard so I'm not the right
person to decide on that.

> > It is all explained it detail in:
> >
> > http://www.postgresql.org/docs/8.0/static/sql-syntax.html#SQL-SYNTAX-IDENTIFIERS
>
>     Seeing as the last para in 4.1.1. Identifiers and Key Words seems to
>     be almost exactly what you came up with (not accusing you of
>     "plagiarism" or such, the wording is obvious, and different people
>     will arrive at virtually identical explanations), wouldn't just
>     linking there suffice? (I'm a bit worried about information scatter
>     and duplication).

Heh, it is the same really. I guess after a certain number of times you
just end up saying the same thing as the docs. I guess it could be
trimmed to remove the duplication...

--
Martijn van Oosterhout   <kleptog@svana.org>   http://svana.org/kleptog/
> Patent. n. Genius is 5% inspiration and 95% perspiration. A patent is a
> tool for doing 5% of the work and then sitting around waiting for someone
> else to do the other 95% so you can sue them.

Вложения

Re: 5 new entries for FAQ

От
Bruce Momjian
Дата:
Martijn van Oosterhout wrote:
-- Start of PGP signed section.
> Hi,
>
> After going through pgsql-general a bit I figured there were a few
> important questions missing from the FAQ, so I wrote some.
>
> Comments welcome. I can write more, if people can suggest things to
> write about. I was thinking something about collation and locales but
> I'm sure sure I understand them myself.

I have updated the FAQ to handle three of the items you mentioned.  In
one case, I added a new FAQ entry (double-quoting identifiers with a
link to our docs), and in two other cases (indexing long columns,
case-insensitive columns) I added to existing FAQ items where
appropriate.  Patch attached and applied.

For the batch job and single-CPU issues, they did not fit into existing
FAQ entries, and I am not sure they are asked enough to be added as
FAQs.  I am interested to hear other's opinions on this.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073
Index: doc/src/FAQ/FAQ.html
===================================================================
RCS file: /cvsroot/pgsql/doc/src/FAQ/FAQ.html,v
retrieving revision 1.310
diff -c -c -r1.310 FAQ.html
*** doc/src/FAQ/FAQ.html    30 May 2005 13:11:06 -0000    1.310
--- doc/src/FAQ/FAQ.html    10 Aug 2005 19:26:19 -0000
***************
*** 116,122 ****
      does not exist" errors when accessing temporary tables in PL/PgSQL
      functions?<BR>
       <A href="#4.20">4.20</A>) What replication solutions are available?<BR>
!

      <HR>

--- 116,124 ----
      does not exist" errors when accessing temporary tables in PL/PgSQL
      functions?<BR>
       <A href="#4.20">4.20</A>) What replication solutions are available?<BR>
!      <A href="#4.21">4.21</A>) Why are my table and column names not
!     recognized in my query?<BR>
!

      <HR>

***************
*** 613,618 ****
--- 617,628 ----
      <P>The maximum table size and maximum number of columns can be
      quadrupled by increasing the default block size to 32k.</P>

+     <P>One limitation is that indexes can not be created on columns
+     longer than about 2,000 characters. Fortunately, such indexes are
+     rarely needed. Uniqueness is best guaranteed using another column
+     that is an MD5 hash of the long column, and full text indexing
+     allows for searching of words within the column.</P>
+
      <H3><A name="4.5">4.5</A>) How much database disk space is required
      to store data from a typical text file?</H3>

***************
*** 740,746 ****
  <PRE>
      CREATE INDEX tabindex ON tab (lower(col));
  </PRE>
!
      <H3><A name="4.9">4.9</A>) In a query, how do I detect if a field
      is <SMALL>NULL</SMALL>?  How can I sort on whether a field is <SMALL>
      NULL</SMALL> or not?</H3>
--- 750,761 ----
  <PRE>
      CREATE INDEX tabindex ON tab (lower(col));
  </PRE>
!     <P>If the above index is created as <SMALL>UNIQUE</SMALL>, though
!     the column can store upper and lowercase characters, it can not have
!     identical values that differ only in case. To force a particular
!     case to be stored in the column, use a <SMALL>CHECK</SMALL>
!     constraint or a trigger.</P>
!
      <H3><A name="4.9">4.9</A>) In a query, how do I detect if a field
      is <SMALL>NULL</SMALL>?  How can I sort on whether a field is <SMALL>
      NULL</SMALL> or not?</H3>
***************
*** 1000,1004 ****
--- 1015,1036 ----

      <P>There are also commercial and hardware-based replication solutions
      available supporting a variety of replication models.</P>
+
+     <H3><A name="4.20">4.20</A>) Why are my table and column names not
+     recognized in my query?</H3>
+
+     <P>The most common cause is the use of double-quotes around table or
+     column names during table creation. When double-quotes are used,
+     table and column names (called identifiers) are stored <a
+     href="http://www.postgresql.org/docs/8.0/static/sql-syntax.html#SQL-
+     SYNTAX-IDENTIFIERS">case-sensitive</a>, meaning you must use
+     double-quotes when referencing the names in a query. Some interfaces,
+     like pgAdmin, automatically double-quote identifiers during table
+     creation. So, for identifiers to be recognized, you must either:
+     <UL>
+     <LI>Avoid double-quoting identifiers when creating tables</LI>
+     <LI>Use only lowercase characters in identifiers</LI>
+     <LI>Double-quote identifiers when referencing them in queries</LI>
+     </UL>
    </BODY>
  </HTML>

Re: 5 new entries for FAQ

От
Dan Armbrust
Дата:
Bruce Momjian wrote: <blockquote cite="mid200508101933.j7AJXGU12502@candle.pha.pa.us" type="cite"><br /><pre wrap="">
I have updated the FAQ to handle three of the items you mentioned.  In
one case, I added a new FAQ entry (double-quoting identifiers with a
link to our docs), and in two other cases (indexing long columns,
case-insensitive columns) I added to existing FAQ items where
appropriate.  Patch attached and applied.

For the batch job and single-CPU issues, they did not fit into existing
FAQ entries, and I am not sure they are asked enough to be added as
FAQs.  I am interested to hear other's opinions on this. </pre></blockquote><blockquote type="cite"><pre
wrap="">***************
*** 613,618 ****
--- 617,628 ----     <P>The maximum table size and maximum number of columns can be     quadrupled by increasing
thedefault block size to 32k.</P> 
 
+     <P>One limitation is that indexes can not be created on columns
+     longer than about 2,000 characters. Fortunately, such indexes are
+     rarely needed. Uniqueness is best guaranteed using another column
+     that is an MD5 hash of the long column, and full text indexing
+     allows for searching of words within the column.</P>
+      <H3><A name="4.5">4.5</A>) How much database disk space is required     to store data from a
typicaltext file?</H3></pre></blockquote><blockquote cite="mid200508101933.j7AJXGU12502@candle.pha.pa.us"
type="cite"><prewrap=""><hr size="4" width="90%" /> </pre></blockquote> I liked the FAQ entry written up by the
originalsubmitter much better, WRT to the long index issue.  This write up does not contain the actual error message
encountered,so its not going to be found by someone looking for a solution to the problem.  It doesn't contain the
optionalworkaround, and it doesn't have a link into the full text searching features as the recommended fix.  I was one
ofthe more recent people to encounter this problem, and I don't think that this FAQ would have helped me (if I even saw
it,because google certainly won't pick it up in a way that most people will search when the encounter the issue - they
aregoing to put in the error message)<br /><br /> Dan<br /><pre class="moz-signature" cols="72">-- 
 
****************************
Daniel Armbrust
Biomedical Informatics
Mayo Clinic Rochester
daniel.armbrust(at)mayo.edu
<a class="moz-txt-link-freetext" href="http://informatics.mayo.edu/">http://informatics.mayo.edu/</a>
</pre>

Re: 5 new entries for FAQ

От
Bruce Momjian
Дата:
Dan Armbrust wrote:
> I liked the FAQ entry written up by the original submitter much better,
> WRT to the long index issue.  This write up does not contain the actual
> error message encountered, so its not going to be found by someone
> looking for a solution to the problem.  It doesn't contain the optional
> workaround, and it doesn't have a link into the full text searching
> features as the recommended fix.  I was one of the more recent people
> to encounter this problem, and I don't think that this FAQ would have
> helped me (if I even saw it, because google certainly won't pick it up
> in a way that most people will search when the encounter the issue -
> they are going to put in the error message)
> Dan

True, but we don't have an FAQ that hits every single problem users will
encounter.  We try to make the FAQ concise so most people will read all
the items.  If the item come up more often, we will consider making it
more prominent.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

Re: 5 new entries for FAQ

От
Martijn van Oosterhout
Дата:
On Wed, Aug 10, 2005 at 03:33:16PM -0400, Bruce Momjian wrote:
> For the batch job and single-CPU issues, they did not fit into existing
> FAQ entries, and I am not sure they are asked enough to be added as
> FAQs.  I am interested to hear other's opinions on this.

Maybe, just looking through my email and my memories they've been a few
times. How often a question needs to be asked before putting it in the
FAQ is easier than answering it each time, well, that's a matter of
debate.

The other extreme is the Exim FAQ which is huge, but it has answered
every question I've ever asked. Not sure if that's a goal though.
--
Martijn van Oosterhout   <kleptog@svana.org>   http://svana.org/kleptog/
> Patent. n. Genius is 5% inspiration and 95% perspiration. A patent is a
> tool for doing 5% of the work and then sitting around waiting for someone
> else to do the other 95% so you can sue them.

Вложения

Re: 5 new entries for FAQ

От
Bruce Momjian
Дата:
pgman wrote:
> Dan Armbrust wrote:
> > I liked the FAQ entry written up by the original submitter much better,
> > WRT to the long index issue.  This write up does not contain the actual
> > error message encountered, so its not going to be found by someone
> > looking for a solution to the problem.  It doesn't contain the optional
> > workaround, and it doesn't have a link into the full text searching
> > features as the recommended fix.  I was one of the more recent people
> > to encounter this problem, and I don't think that this FAQ would have
> > helped me (if I even saw it, because google certainly won't pick it up
> > in a way that most people will search when the encounter the issue -
> > they are going to put in the error message)
> > Dan
>
> True, but we don't have an FAQ that hits every single problem users will
> encounter.  We try to make the FAQ concise so most people will read all
> the items.  If the item come up more often, we will consider making it
> more prominent.

I thought again about your issue and I now remember the proper way to
help users in this case is to improve the error message.  I have added a
"hint" message for the case of indexing large values, patch attached.

[ Sorry about a patch to general but it seems necessary in this case.]

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073
Index: src/backend/access/hash/hashinsert.c
===================================================================
RCS file: /cvsroot/pgsql/src/backend/access/hash/hashinsert.c,v
retrieving revision 1.36
diff -c -c -r1.36 hashinsert.c
*** src/backend/access/hash/hashinsert.c    21 Mar 2005 01:23:57 -0000    1.36
--- src/backend/access/hash/hashinsert.c    10 Aug 2005 21:27:50 -0000
***************
*** 88,94 ****
                  (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
                   errmsg("index row size %lu exceeds hash maximum %lu",
                          (unsigned long) itemsz,
!                         (unsigned long) HashMaxItemSize((Page) metap))));

      /*
       * Compute the target bucket number, and convert to block number.
--- 88,95 ----
                  (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
                   errmsg("index row size %lu exceeds hash maximum %lu",
                          (unsigned long) itemsz,
!                         (unsigned long) HashMaxItemSize((Page) metap)),
!                  errhint("Values larger than a buffer page cannot be indexed.")));

      /*
       * Compute the target bucket number, and convert to block number.
Index: src/backend/access/nbtree/nbtinsert.c
===================================================================
RCS file: /cvsroot/pgsql/src/backend/access/nbtree/nbtinsert.c,v
retrieving revision 1.121
diff -c -c -r1.121 nbtinsert.c
*** src/backend/access/nbtree/nbtinsert.c    6 Jun 2005 20:22:57 -0000    1.121
--- src/backend/access/nbtree/nbtinsert.c    10 Aug 2005 21:27:51 -0000
***************
*** 392,398 ****
                  (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
                   errmsg("index row size %lu exceeds btree maximum, %lu",
                          (unsigned long) itemsz,
!                         (unsigned long) BTMaxItemSize(page))));

      /*
       * Determine exactly where new item will go.
--- 392,401 ----
                  (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
                   errmsg("index row size %lu exceeds btree maximum, %lu",
                          (unsigned long) itemsz,
!                         (unsigned long) BTMaxItemSize(page)),
!                  errhint("Values larger than 1/3 of a buffer page cannot be indexed\n"
!                          "Consider a separate column containing an MD5 hash of the value\n"
!                          "or use full text indexing.")));

      /*
       * Determine exactly where new item will go.
Index: src/backend/access/nbtree/nbtsort.c
===================================================================
RCS file: /cvsroot/pgsql/src/backend/access/nbtree/nbtsort.c,v
retrieving revision 1.91
diff -c -c -r1.91 nbtsort.c
*** src/backend/access/nbtree/nbtsort.c    6 Jun 2005 20:22:57 -0000    1.91
--- src/backend/access/nbtree/nbtsort.c    10 Aug 2005 21:27:52 -0000
***************
*** 498,504 ****
                  (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
                   errmsg("index row size %lu exceeds btree maximum, %lu",
                          (unsigned long) btisz,
!                         (unsigned long) BTMaxItemSize(npage))));

      if (pgspc < btisz || pgspc < state->btps_full)
      {
--- 498,507 ----
                  (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
                   errmsg("index row size %lu exceeds btree maximum, %lu",
                          (unsigned long) btisz,
!                         (unsigned long) BTMaxItemSize(npage)),
!                  errhint("Values larger than 1/3 of a buffer page cannot be indexed\n"
!                          "Consider a separate column containing an MD5 hash of the value\n"
!                          "or use full text indexing.")));

      if (pgspc < btisz || pgspc < state->btps_full)
      {
Index: src/backend/access/rtree/rtree.c
===================================================================
RCS file: /cvsroot/pgsql/src/backend/access/rtree/rtree.c,v
retrieving revision 1.90
diff -c -c -r1.90 rtree.c
*** src/backend/access/rtree/rtree.c    6 Jun 2005 17:01:22 -0000    1.90
--- src/backend/access/rtree/rtree.c    10 Aug 2005 21:27:52 -0000
***************
*** 733,739 ****
                  (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
                   errmsg("index row size %lu exceeds rtree maximum, %lu",
                          (unsigned long) newitemsz,
!                         (unsigned long) RTPageAvailSpace)));

      maxoff = PageGetMaxOffsetNumber(page);
      newitemoff = OffsetNumberNext(maxoff);        /* phony index for new
--- 733,740 ----
                  (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
                   errmsg("index row size %lu exceeds rtree maximum, %lu",
                          (unsigned long) newitemsz,
!                         (unsigned long) RTPageAvailSpace),
!                  errhint("Values larger than a buffer page cannot be indexed.")));

      maxoff = PageGetMaxOffsetNumber(page);
      newitemoff = OffsetNumberNext(maxoff);        /* phony index for new

Re: 5 new entries for FAQ

От
Tino Wildenhain
Дата:
Am Mittwoch, den 10.08.2005, 17:38 -0400 schrieb Bruce Momjian:
> "Consider a separate column containing an MD5 hash of the value\n"

wouldnt a functional index over md5 hash of the original value
be a bit better?




Re: 5 new entries for FAQ

От
Bruce Momjian
Дата:
Tino Wildenhain wrote:
> Am Mittwoch, den 10.08.2005, 17:38 -0400 schrieb Bruce Momjian:
> > "Consider a separate column containing an MD5 hash of the value\n"
>
> wouldnt a functional index over md5 hash of the original value
> be a bit better?

Yes, good point.  Let me adjust the text.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

Re: 5 new entries for FAQ

От
"Jim C. Nasby"
Дата:
On Wed, Aug 10, 2005 at 11:22:58PM +0200, Martijn van Oosterhout wrote:
> On Wed, Aug 10, 2005 at 03:33:16PM -0400, Bruce Momjian wrote:
> > For the batch job and single-CPU issues, they did not fit into existing
> > FAQ entries, and I am not sure they are asked enough to be added as
> > FAQs.  I am interested to hear other's opinions on this.
>
> Maybe, just looking through my email and my memories they've been a few
> times. How often a question needs to be asked before putting it in the
> FAQ is easier than answering it each time, well, that's a matter of
> debate.
>
> The other extreme is the Exim FAQ which is huge, but it has answered
> every question I've ever asked. Not sure if that's a goal though.

My experience is that long FAQ's are fine, so long as they're easy to
search through. This means you've got to support users who may not know
the magic word to search on. A good example is finding the limits for
how many rows in a table; searching on limit gets you nothing.

The alternative is to make it very easy for users to skim through the
TOC to find what they need. Right now that's not very easy to do because
2 of the catagories are over 9 items long (humans deal with info best in
chunks of 5-9 items; most people do best with 7 items or less).
--
Jim C. Nasby, Sr. Engineering Consultant      jnasby@pervasive.com
Pervasive Software        http://pervasive.com        512-569-9461

Re: 5 new entries for FAQ

От
Martijn van Oosterhout
Дата:
On Tue, Aug 16, 2005 at 01:20:29AM -0500, Jim C. Nasby wrote:
> My experience is that long FAQ's are fine, so long as they're easy to
> search through. This means you've got to support users who may not know
> the magic word to search on. A good example is finding the limits for
> how many rows in a table; searching on limit gets you nothing.

But searching for limit works depending on you search engine, since the
word "limits" appears once. Maybe it's planning or just luck but the
Exim FAQ [1] has always had the question exactly the way I phrased it,
which means even though it has hundreds of questions, it works.

I think the trick is to:
 - Include relevent keywords: error messages, config options, command names
 - State the question multiple ways if there's no obvious best

> The alternative is to make it very easy for users to skim through the
> TOC to find what they need. Right now that's not very easy to do because
> 2 of the catagories are over 9 items long (humans deal with info best in
> chunks of 5-9 items; most people do best with 7 items or less).

I imagine that perhaps what is needed is a database that has (at least)
a reference to every single possible error message and what it means. I
guess you could call it a "knowledgebase" and there'd be no reason to
keep it small.

I was thinking of more categories, but whatever you do it would make
the FAQ a lot bigger which appears not to be the goal. Although I admit
to reading large chunks of the Exim FAQ because it is full of examples,
just to get a feel of what's possible.

Anyway, I dropped my patch, it's still in the archive and hopefully
this thread has created a enough links to make google take notice. Some
questions now have this patch in the search result so perhaps things
are working as intended.

[1] http://www.exim.org/exim-html-4.30/doc/html/FAQ.html

Have a nice day,
--
Martijn van Oosterhout   <kleptog@svana.org>   http://svana.org/kleptog/
> Patent. n. Genius is 5% inspiration and 95% perspiration. A patent is a
> tool for doing 5% of the work and then sitting around waiting for someone
> else to do the other 95% so you can sue them.

Вложения