Thread: improve routine vacuuming docs

This patch makes some improvements and adds some details to the
documentation on routine database maintenance activities. Any comments
on the new text would be appreciated. I decided not to mention the
FSM -- I haven't seen any reports that users have had to tweak FSM
settings in 7.4, and it is probably better not to get into
implementation details unless there's a good reason for it. But if
anyone thinks otherwise, please speak up.

I also corrected a bunch of instances of SGML usage. One of these
days I'll get around to writing a style guide for the PostgreSQL SGML
docs...

-Neil

Robert Treat <xzilla@users.sourceforge.net> writes:
> Should be "TRUNCATE removes the <emphasis>entire</emphasis> content of
> the table immediately, without requiring a subsequent
> <command>VACUUM</command> or <command>VACUUM FULL</command> to
>      reclaim the now-unused disk space."

I think the <emphasis/> is overkill, but otherwise I've made this
change.

> Maybe better is  ..."risk of OID wraparound failures".

Why? XID wraparound and OID wraparound are completely distinct
issues. I think from the context it's pretty clear that XID wraparound
is what is being referred to here.

> What differentiates the first SELECT as a command and the second
> SELECT as a literal?  Some question for CASE really...

Well, the rule-of-thumb is that SQL commands are marked with
<command/>, but clauses of commands or entire example queries are
marked with <literal/>. I think the <literal>CASE</> is correct, but
on closer examination, the second SELECT should probably also be
marked with <command/>.

I've attached a revised patch that incorporates these changes. Thanks
for the feedback!

-Neil

Neil Conway wrote:
> This patch makes some improvements and adds some details to the
> documentation on routine database maintenance activities. Any
> comments on the new text would be appreciated.

It's kind of hard to see what you have really changed.  Can you provide
a summary?

> I also corrected a bunch of instances of SGML usage. One of these
> days I'll get around to writing a style guide for the PostgreSQL SGML
> docs...

Please do.  But note that the first thing I'd add to such a document
would be not to write things like that:

    You should <command>VACUUM</command> your database every day.

Instead, either write

    You should vacuum your database every day.

or

    You should run the command <command>VACUUM</command> in your
    database every day.

If you need a verb, write a verb; don't abuse nouns.

Peter Eisentraut <peter_e@gmx.net> writes:
> It's kind of hard to see what you have really changed.  Can you
> provide a summary?

The majority of the changes are in the 3rd patch hunk; ISTM it is
pretty easy to see what has been changed. I spent more time discussing
the differences between VACUUM and VACUUM FULL, added a note that some
update-intensive sites VACUUM as frequently as every five minutes, and
so on.

>     You should <command>VACUUM</command> your database every day.
>
> Instead, either write
>
>     You should vacuum your database every day.

Well, my reasoning was that the phrase "VACUUM", particularly when
typeset as a command, has an exact technical meaning within the
context of PostgreSQL. It is derived from the English word "vacuum",
but our usage of the term differs significantly from any definition
you'd find in a normal dictionary. For example, I don't think this is
optimal:

    The presence of a for update trigger on the table [...]

(To invent a random example) I think this is clearer:

    The presence of a <literal>FOR UPDATE</literal> trigger on the
    table [...]

Here, the PG-specific term is differently typeset and capitalized.

However, I Am Not A Technical Writer, so I may be completely
wrong. BTW, can anyone recommend a good book on technical writing in
English?

-Neil

Neil Conway <neilc@samurai.com> writes:
> I've attached a revised patch that incorporates these
> changes. Thanks for the feedback!

Patch applied to HEAD. Thanks again, Robert & Peter.

-Neil

Neil Conway wrote:
> Well, my reasoning was that the phrase "VACUUM", particularly when
> typeset as a command, has an exact technical meaning within the
> context of PostgreSQL.

The difference is that "VACUUM" is clearly meant to refer to the
command, and as such it is not a verb.  So write "run [the command]
VACUUM" and you're on the safe side.  That also saves you from creating
entities like "VACUUMing", which are beyond ugly.

>     The presence of a for update trigger on the table [...]
>
> (To invent a random example) I think this is clearer:
>
>     The presence of a <literal>FOR UPDATE</literal> trigger on the
>     table [...]

This is OK, because in English you can use almost anything as an
adjective.

> However, I Am Not A Technical Writer, so I may be completely
> wrong. BTW, can anyone recommend a good book on technical writing in
> English?

I find that "The Chicago Manual of Style" has answered all my questions
so far.  That's not targeted specially at technical writing, but it's
good allround information.