I believe that all the details must be added to the document. I (for one) faced problems and spent a lot of time to discover many important points. But I could save that precious time or spend it on coding my mods if they were written in a document. You and a few other people have surely performed your own tests and have discovered the same points independently. Now that some of us have found some important points, not to add them to the document means that others will sooner or later face the same problems and will have to perform the same tests to discover the same results.
For example, here are the descriptions of "ForceSpell" and "ReallyForceSpell" in the current (newly released) version of IESDP:
QUOTE
113 ForceSpell(O:Target,I:Spell*Spell)
Forces the object to cast the specified spell. The spell cannot be interrupted and the object does not need to have the spell memorized or even have the spell. Used by traps a lot to create the trap damage. The casting creature must meet the level requirements as set in the spell file.
QUOTE
181 ReallyForceSpell(O:Target,I:Spell*Spell)
This is yet another action in the Spell() family. This command will do the same thing as ForceSpell(), but with 0 casting time. The casting creature must meet the level requirements as set in the spell file.
At least, these additional important information should also be added:
1- ForceSpell and ReallyForceSpell allow casting spells on partially visible creatures (which is illegal). Partially visible creatures are only subject to physical attacks, but ForceSpell and ReallyForceSpell allow casting spells on them. SpellNoDec doesn't have this problem. Of course, there are cases in which we cannot use SpellNoDec because we need ZERO spellcasting time (for example when coding chain contingencies or spell sequencers). In such cases, we have to solve this problem by adding a trigger (!StateCheck(LastSeenBy(Myself),STATE_IMPROVEDINVISIBILITY) in the same block.
2- ForceSpell and ReallyForceSpell also allow casting spell on creature who are behind closed doors!! (let alone casting spells on creatures who stand out of the spell range). SpellNoDec doesn't have this problem.
3- ForceSpell doesn't respect the standard delay (pause) between spells (while SpellNoDec does)
My point is that the document should be such that all of the differences between these different actions are clearly mentioned in it. I have tested and found them all for myself. Some other modders might have done the same. But if the document contains these important points, others will not have to spend so much time to test and discover them one by one in the future. What is the point of the document if modders will have to test everything themselves?
Now that some of us have performed these tests and have discovered these points, why not to add them to the document?