https://www.mediawiki.org/wiki/Help:Notifications should also be updated and has the advantage of being translatable.

We probably shouldn't add each part until it has actually been merged!

TL;DR: I've put a draft of the expanded Mention Notifications description in https://www.mediawiki.org/wiki/User:Leszek_Manicki_(WMDE)/Help:Notifications/Notification_types#Mentions

I've copied over current version of Manual:Echo to https://www.mediawiki.org/wiki/User:Leszek_Manicki_(WMDE)/Echo and updated links to specific places in code (ie. line numbers). I've also expanded it a bit.

That said I am not really convinced it actually makes sense to improve this particular page. It seems to serve as a kind of guide to end users (what to do to ping a user) but on the other hand it provides quite detailed low-level description (other's signatures cannot be present in the message, what section levels are allowed, how variables are expanded, how to link to a user etc) with all those links to particular lines of Echo's code.
I believe a bit more general description including information what steps to take in order to ping a user should be enough for (most) users. This kind of help has already been provided in https://www.mediawiki.org/wiki/Help:Notifications/Notifications_types#Mentions.
I've copied this page over to https://www.mediawiki.org/wiki/User:Leszek_Manicki_(WMDE)/Help:Notifications/Notification_types#Mentions and started to expand it. All comments and edits are welcome.

And as far as referring to the code is concerned I don't think putting this on wiki page is really useful. Every time the code changes it is potentially needed to update the page, even if the change is completely non-functional (ie. adding a comment somewhere above relevant lines). Otherwise references are out of sync and might not be very helpful. I think it would rather be useful to invest some time to improve the in-code documentation (e.g. by improving tests which will also show what usage is allowed and what is not, and adding comments where it makes sense).

Similar concerns have been IMO already raised in https://www.mediawiki.org/wiki/Manual_talk:Echo. I believe in order to be actually useful Manual:Echo should be completely re-created. OTOH I am not really sure what this page should include. General "technical" issues related to the extension itself are on Extension:Echo page.

My understanding of what the background of this ticket is that there has been some amount of confusion among the users, why some "mentions" don't get sent, and how does on actually do those mentions properly. I believe clarifying such issues could be pretty much achieved by expanding Help:Notifications. If there are some more detailed issues with some special cases not covered by the (soon-to=be=improved) help, those could be discussed on the help's discussion page. Some general "Mentions problems" subpage could be also created somewhere (not sure if as a subpage of the Help:Notifications, though) but right now it is not really clear to me if it is really needed.

And I entirely agree with @Addshore that "mentioning self" and "easy mention failure notifications" should only be reflected in the help/manual page (be it whatever page in the end) once the features are implemented (ie. merged)! There is clearly some work left to be done with this ticket but documenting new features should not block closing the ticket IMO.

To sum up: At this point a reasonable way forward would be for me to expand Mentions sections of the Help:Notifications subpage, and working with interested people on either completely rebuilding or removing Manual:Echo.

If referring to the code is really needed/expected we could have those references more "reliable" by making references to a line in a particular version (ie. git commit). But this still seems not that nice to me.

Some progress has been made

• Failed mention and Succesful mention notifications have been described in https://www.mediawiki.org/wiki/Help:Notifications/Notifications_types#Future_notifications. Those descriptions should be moved to Default notification sections once they got enabled on "real" wikis.
• mentioning self is now possible and mentioned in https://www.mediawiki.org/wiki/Help:Notifications/Notifications_types#Mentions
• information on mentions in https://www.mediawiki.org/wiki/Help:Notifications/Notifications_types#Mentions has been slightly expanded to give users more details how to it, and what not to do. If we would like to provide even more detailed information on mentioning, we could start a subpage (e.g. Help:Notifications/Notifications/Mentions or so) devoted to mentions only. Do we want to have it depends how much extra information compared to the existing section of Help:Notifications/Notification_types do we actually could and want to provide to users.
• I tried to start discussion on possible moving some contents from Manual:Echo somewhere else but no changes here yet.