Documentation Contradiction: insert methods inside a change() method

[ajhuntsman]

Under the Inserting Data heading, there's a yellow warning: "You cannot use the insert methods inside a change() method. Please use the up() and down() methods."

But just above on the same page, under The Change Method the last code sample invokes an insert() method from within the change() method.

If this code sample is actually valid, is it because the invocation of insert() is conditional based on isMigratingUp()? If so, that should be explained in the yellow warning under Inserting Data.

Perhaps this:

"Please use the up() and down() methods."

Could be changed to this:

"Please use the up() and down() methods, or when inside a change() method only invoke insert() inside a conditional block when isMigratingUp() or isMigratingDown() is true."

[MasterOdin]

insert will only function when operating in the up directory and will throw in the down direction regardless of if you wrap it in a if (!isMigrationUp()) block or otherwise (as we have no way of knowing that you've done so).

I agree that we should update the docs to reflect this, especially as we give an example of it elsewhere as you way.