I append here what we emailed some time about documentation:
Deployment: path where to deploy the plugin and how to deploy.
CLI scripts: explain how to use them, and how to extend them at your side.
Reformatting strings: like "For logging or security reasons we are skipping mdl_user_info_data, mdl_user_lastaccess, mdl_user_preferences, mdl_user_private_key." for a new one that would explain better. Perhaps with a link to the README.txt.
Merging logs: If nothing is merged (due to some reason like the old user is just created, without any kind of log), show a message that would explain that situation.
Change messages about rolling back actions: the plugin should detect, using the $DB object I suppose, whether the current database supports transactions, so that we do know if actions will be always done (if not supported) or rolled back (if supported). For instance, the message about failed merging actions should be revisited in this way.
Explain how to recover the list of old merging actions (See merging logs).
Maybe improve in some way the special cases explanations. May be we could split between omitting tables and tables with compound indexes.
Extending local settings with a config/config.local.php. I think it is poorly documented.
See especially comments in https://tracker.moodle.org/browse/MDL-24443 between 20/Jan/14 and 22/Jan/14