improve routine vacuuming docs

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.