Here are some review comments for the v19-0001 docs patch.
The content seemed reasonable, but IMO it should be presented quite differently.
~~~~
1. Use sub-sections
I expect this logical replication "Conflicts" section is going to
evolve into something much bigger. Surely, it's not going to be one
humongous page of details, so it will be a section with lots of
subsections like all the other in Chapter 29.
IMO, you should be writing the docs in that kind of structure from the
beginning.
For example, I'm thinking something like below (this is just an
example - surely lots more subsections will be needed for this topic):
29.6 Conflicts
29.6.1. Conflict types
29.6.2. Logging format
29.6.3. Examples
Specifically, this v19-0001 patch information should be put into a
subsection like the 29.6.2 shown above.
~~~
2. Markup
+<screen>
+LOG: conflict detected on relation "schemaname.tablename":
conflict=<literal>conflict_type</literal>
+DETAIL: <literal>detailed explaination</literal>.
+<literal>Key</literal> (column_name, ...)=(column_name, ...);
<literal>existing local tuple</literal> (column_name,
...)=(column_name, ...); <literal>remote tuple</literal> (column_name,
...)=(column_name, ...); <literal>replica identity</literal>
(column_name, ...)=(column_name, ...).
+</screen>
IMO this should be using markup more like the SQL syntax references.
- e.g. I suggest <synopsis> instead of <screen>
- e.g. I suggest all the substitution parameters (e.g. detailed
explanation, conflict_type, column_name, ...) in the log should use
<replaceable class="parameter"> and use those markups again later in
these docs instead of <literal>
~
nit - typo /explaination/explanation/
~
nit - The amount of scrolling needed makes this LOG format too hard to
see. Try to wrap it better so it can fit without being so wide.
~~~
3. Restructure the list
+ <itemizedlist>
+ <listitem>
I suggest restructuring all this to use a nested list like:
LOG
- conflict_type
DETAIL
- detailed_explanation
- key
- existing_local_tuple
- remote_tuple
- replica_identity
Doing this means you can remove a great deal of the unnecessary junk
words like "of the first sentence in the DETAIL", and "sentence of the
DETAIL line" etc. The result will be much less text but much simpler
text too.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
