Posted by member 37809 on 2003-07-10 10:26:08 link

Everything in moderation is good for the intent of understandability. The amount of config documentation you need is probably proportional to the complexity of your theme (scripted and behavioral config versus attribute config? *shrug*). Keep it brief in the config and if you have to, place general explanatory config-related docs in a file other than the readme. The readme is typically used to clarify setup, intended usage, issues and other happenings in the end user experience.

Comment on non-obvious stuff and things that seem wrong (workarounds, etc, that the user may have the urge to 'correct'). Depending on how complex and indescribable the names of things do you then have to explain. Try to choose good names and you don't have to comment, unless the theme is a big project (for your own sake). If you split the rc, make sure the names of the files reflect well the reason for splitting, and avoid ambiguous names like 'system', 'script', unless they are very general or the quantity is small.

If you feel that some setting or group of settings working together may be arguably a personal preference, make it your own evar w/ if/else, putting the evar in a friendly config file (e.g. OTS themevars.rc, etc) or if it is less potentially personal put the setting in the RC anyway. Place these in your RC even if you could omit them because they are default values to the module. If you do want to explicitly encourage reuse of some config you might comment on that too, and make it easily adaptable to somewhere else.