Documentation for new users

I'm mostly drawing from my experience with switching my login shell to ion here. There were a few small hiccups that I experienced due to something either not being obvious at first glance through the docs or found under a different heading to expected.

1. @ sigil. I was aware of this through the "Introduction" section, but wasn't expecting it to affect commands such as ssh luke@10.10.10.10 or scp equivalent. I wonder if a page on sigils would be helpful? Even if it repeated information that is found elsewhere, a user could scan the contents listing and see the title easily.
2. Colours in prompts - this is a real non-obvious one. A search of both spellings revealed nothing, and I had to find a random initrc example to grok it. Probably a misunderstanding on my part of how shells parse the prompt.
3. Point 2 leads in to ${color::light_magenta}, ${super::<something>} and similar - there didn't appear to be anything in the docs detailing how this notation worked?

Maybe a page for people coming from bash-like shells could be helpful also?