From 082b36430df896e29b2d701e293ce6982d5fa38e Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Thu, 1 Jun 2023 13:22:41 -0500 Subject: [PATCH] More conventions used when writing docs --- doc/README | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/doc/README b/doc/README index c004e5d..cc63b6c 100644 --- a/doc/README +++ b/doc/README @@ -2,4 +2,29 @@ The documentation is written in RST, processed with Sphinx and it's extensions. There are a number of conventions: The section "underline" hierarchy is as given in the RST docs: -https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections \ No newline at end of file +https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections + +Each table, and each column, has replacement text defined in epilog.rst.m4. +This is so that the section headings can have "extra comment" in them. +(Simplest to just always have replacement text, rather than worrying about +whether to use :ref:`foo` or |foo|.) + +Each table and column has replacement text defined which makes up the +comment put into the database to describe the table or column. The +name of the repacement text is TABLENAME_summary or +TABLENAME.ColumnName_summary. Usually, the documentation of the table +or column begins with the replacement text. + +Validation rules involving individual columns are documented in the +column's description. Rules involving multiple columns, or multiple +tables, are documented in the table's description. When more than one +table is involved the rule is described only once, ideally in the +table which is on the "one" side of whatever one-to-many relationships +are involved. + +Validation rules should be described in terms of table rows and column +values, although there is nothing wrong with also having text which +explains the real-world implications of the rule. (Likewise with +error messages generated by the database's rules themselves. Without +knowing what the problem is in terms of rows and columns it is not +clear, operationally, how to fix a rule violation.) -- 2.34.1