Hi,
*Everything* in this project is table driven. The tables are formalized in relational database(s).Configuration/operation parameters are just *typed* "fields" in "tables". E.g., "StartColumn" could be a "small integer" constrained to [1..80]; "BackgroundColor" can be one of {Red,Green,Yellow,Lavender}; etc.
The capabilities of the RDBMS are used to do much of the checking and enforcement -- an application is free to *use* values retrieved from the RDBMS *without* examining them for validity because the RDBMS's contract with the application
*ensures* that the values are ALWAYS valid.I can easily show the user what type of datum is expected. I can also show the constraints placed on those data (within reason -- i.e., if a TRIGGER verifies that the value is a prime number, there is no way to algorithmically explain that to the user... I'd have to rely on commentary).
But, examining schemes that are typically used to document (i.e., "assist the user in making choices") settings, there seems to be no clear cut practice for doing so. Indeed, most settings seem to be undocumented. Even knowing that a setting
*might* exist is BFM!(e.g., when I port a desktop application, I grep the sources for structures that enumerate options and build my documentation from those directly -- man pages often lack many such details)
What I think sounds reasonable is to tag each field with "suitably verbose commentary" written from the user's perspective (i.e., NOT the database designer's!) explaining the role of the field. If there are dependencies on other fields (foreign keys, indices, etc.), I can algorithmically embelish that description (since those relations are defined within the RDBMS itself). Tagging individual records with similar descriptions would allow me to automate the presentation of multiple-choice type fields.
E.g., if "SortOrder" is linked to the "Order" field in the "TableOfSortOrders", then I could add a "Description" field to that table resulting in something like:
Order Description
----- ----------- Alpha Left-to-right, alphabetical order (e.g., 1, 11, 12, 2, 3) RevAl Left-to-right, reverse alphabetical order (e.g., Z thru A) Numer Numerical order (e.g., 1, 2, 3, 11, 12)
(obviously, more constrained on space here so I have abbreviated descriptions. In reality, I can be more verbose (within reason).
I suspect this would be enough for someone "determined" to make "the right setting" (i.e., willing to invest the time to read and comprehend the options). For casual/lazy users, I figure there is very little I can do by way of documentation... :<
Any other ideas? I can always say "write up a good description" but that is too easy to blow off. OTOH, providing a convenient place for you to drop in a "short" description and then having an automated framework that extracts other criteria/constraints is probably the best I can do for developers?
Thx,
--don