I'm interested in and excited about oil, but three things have stopped me every time I've tried to give it a go.<p>1. The complete and utter lack of useful documentation. There's not even a link to any docs from the main page of the shell's site. You have to get to the docs from the release page, [1] but I had to find this out by Googling. Given the number of blog-post-like entries in the docs, seems like it would have been less effort and more effective just to write standardized and complete documentation from the start.<p>Just as an example: can anyone tell me what built-ins Oil has, how to use them, and where they are documented? I'll give you a hint. I found out from one of the blog posts that oil has "min" and "max" commands. The following is valid Oil code:<p><pre><code> const x = min(1, 2)
</code></pre>
But what other commands does Oil have, and how do I use them? I have no idea. Some of the doc pages 404 so maybe they're supposed to be there. I have found <i>some</i> pages listing built-ins which are mostly undocumented, but none of them list min or max, so I know they're not complete.<p>2. It's still pretty buggy and lots of features are missing. Development has seemingly moved slowly over the last several years. If it ever did get to the point where I could make it a daily driver then I'd be willing to track down and report bugs, of course.<p>3. I'm a little concerned by how much emphasis is put on POSIX / Bash compatibility. Unless there's going to be a way to <i>fully</i> disable what Oil considers "legacy" language support in a script, then that is going to leave a ton of footguns for people who want to write "modern" Oil code. It's not clear to me whether that's the plan or not (I haven't read every one of the blog posts), but it seems like a mistake to me to sacrifice possible syntax improvements on the altar of compatibility.<p>To be clear, I realize this is basically someone's solo project, and I am impressed by how far it's been taken, just clarifying why I don't think it's ready for general use yet.<p>[1] <a href="https://www.oilshell.org/release/latest/doc/" rel="nofollow">https://www.oilshell.org/release/latest/doc/</a>