Update docs with shell changes and a troubleshooting guide for it