Auto-linking using userIdentity Update #486

The docs on social claims transformations and the starter social and local accounts sample user AlternativeSecurityIds whereas the account linking samples specifically the auto-account-linking sample use UserIdentity to store the social accounts. Which one should we use? It is confusing the see mentions of both. Is there a reason UserIdentity was user instead of alternativeUserIds? If not, could the samples be updated to reflect the current state of the documentation?