Thread: MultiXactId concept underdocumented

MultiXactId concept underdocumented

From
Peter Eisentraut
Date:
The new MultiXactId concept appears in a number of user-facing error
messages, including in the scary context of transaction ID wraparound,
so it seems kind of important, but it doesn't appear to be documented in
any user-facing places.  Should this be rectified?  Maybe some of the
material from README.tuplock should be moved to the user manual.  Maybe
a less jargony term could be found as well.





Re: MultiXactId concept underdocumented

From
Andres Freund
Date:
Hi,


On 2013-08-07 21:25:06 -0400, Peter Eisentraut wrote:
> The new MultiXactId concept appears in a number of user-facing error
> messages, including in the scary context of transaction ID wraparound,
> so it seems kind of important, but it doesn't appear to be documented in
> any user-facing places.  Should this be rectified?  Maybe some of the
> material from README.tuplock should be moved to the user manual.  Maybe
> a less jargony term could be found as well.

Multixacts aren't really new, they've been there since 8.1 or so. It's
just that their use has been a bit expanded and that their internal
format changed a bit.

WRT user facing messages: I think it'd suffice to explain the
anti-wraparound part of the docs that the same holds true for
multixacts. Doing a more detailed explanation seems to require a good
amount of low level explanations and thus seems unlikely to be actually
read.

Greetings,

Andres Freund

-- Andres Freund                       http://www.2ndQuadrant.com/PostgreSQL Development, 24x7 Support, Training &
Services



Re: MultiXactId concept underdocumented

From
Dimitri Fontaine
Date:
Peter Eisentraut <peter_e@gmx.net> writes:
> The new MultiXactId concept appears in a number of user-facing error
> messages, including in the scary context of transaction ID wraparound,
> so it seems kind of important, but it doesn't appear to be documented in
> any user-facing places.  Should this be rectified?  Maybe some of the
> material from README.tuplock should be moved to the user manual.  Maybe
> a less jargony term could be found as well.

In some other Open Source Product Documentations, I've found it very
useful to have a "Glossary" chapter, e.g.
 http://www.gnu.org/software/emacs/manual/html_node/emacs/Glossary.html#Glossary

I think we should consider doing that, mainly copy/pasting definitions
we already have here and there at the beginning of chapters and
sections, and maintain a full Glossary of the technical terms in use
within our product and that you must understand to be able to use it,
either as a developer or a dba or a sysadmin.

Regards,
-- 
Dimitri Fontaine
http://2ndQuadrant.fr     PostgreSQL : Expertise, Formation et Support