On Thu, Jun 12, 2025 at 4:13 AM Peter Smith <smithpb2250@gmail.com> wrote:
>
> Phrases like "... it is recommended..." and "... intended for testing
> and debugging .. " and "... should be used with caution." and "... it
> is advisable to..." seem like indicators that parts of the above
> description should be using SGML markup such as <caution> or <warning>
> or <note> instead of just plain text.
>
I feel WARNING and CAUTION markups could be a little strong for the
concerned case. Such markups are generally used when there is a
side-effect involved with the usage. But in our case, there is no such
side-effect with the API. At max it may fail without harming the
system and will succeed in the next invocation. But I also feel that
such sections catch user attention. Thus if needed, we can have a NOTE
section to convey the recommended way of slot synchronization.
Thoughts?
Similar to our case, I see some other docs using caution words without
a CAUTION markup. Please search for 'caution' in [1],[2],[3]
[1]: https://www.postgresql.org/docs/current/continuous-archiving.html
[2]: https://www.postgresql.org/docs/current/sql-altertable.html
[3]: https://www.postgresql.org/docs/18/oauth-validator-design.html#OAUTH-VALIDATOR-DESIGN-USERMAP-DELEGATION
thanks
Shveta
