How much documentation is needed to be able to easely alter a theme? The answer will of course be different depending on who you ask, so therefore I thought of this poll.

And also, do you have any examples of themes with good config file layout to recomend? Do you prefer split settings (one file for popup settings and so on)?

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.

I would say, for the most obvious settings (location, color, whatever), explanation is not needed. However, for the formulas, if statements, etc, an explanation would definitely be appreciated. either in the step, or in a separate readme.
some of us (me!!) are really bad with math and formulas in general, so trying to figure out what they do (or are supposed to do) is sometimes frustrating.

Depends... if you're making a rather complex theme which isn't meant to be taken apart anyway you won't need many comments.

however, what better way to learn the more advanced stuff that taking apart someone else's theme and changing it to suit their needs?

every theme comes with the modules readmes, i think that's enough explanation.

let me rephrase what you said syro...

every theme SHOULD come with the moduels readmes...

there shouldn't be much reason to comment a theme. step files are notoriously linear. Module readme files shouldn't be in a theme zip either. all that does is pad file size. modules shouldn't conceivably be in a theme zip either. a specification for what version is necessary, if a specific version, should be all that's needed. (of course, this is hard to do, but with loose-screws and ls.net holding onto as many past versions as possible, it gets easier)

thanks DeViLbOi, that sounds much better.

A certain amount of comment is needed in the parts of files that are intend to be easily modified. I think comments in script files should be welcome too; to share tricks.

This is what I think...

But generaly, I don't take time to add more than the title's sections as comment...

Of course, a "How to use this theme" is needed (readme.txt)

I don't do any commenting due to the linear nature of themes but I think those fresh to creating themes may appreciate commenting for little tricks used in a theme.