GitLab Shell developer's guide
There have been several videos and deep dives on various aspects of Shell. It would be useful to have documentation on how the code works internally. Such a guide would describe the main modules and occasionally dive into code, and existing recordings could also be linked. This could help both internal and community contributors in getting started with Shell.
A guide would start with a general roadmap of the shell code, and then include some deep dives into some code areas. Not every part of the code needs to be described, only interesting highlights. It would also be understood that documentation like this can go out of date quickly if there are a lot of updates. This issue could be addressed by nominating a shell version number the documentation page is valid for.
The existing documentation is useful, but the pieces are a bit disconnected and a mix between what is does and how it works internally. We should seperate these things are they are for different audiences.
The Nginx development guide is a great example of such a guide. It balances usefulness against documentation terseness and readily drops into the code.