Documentation suggestions

[indigoviolet]

I have been aware of this project for a while but decided to try and convert some simple shell scripts today. My biggest frustration that is making me abandon this course for now:

The documentation is confusing, missing links and an overall obvious structure, hard to navigate through. Compare to something like https://docs.python.org/3/index.html -- I would suggest an organization like

• Introductions (what is oil, what is osh),
• How-tos (translating common shell idioms to oil -- ideally side-by-side code comparing shell to oil),
• Language tour/details, and
• a Reference detailing syntax and builtins.
• Details for contributors (architecture, philosophy, future directions, development info etc)

In the case of oil, these things are not clearly delineated. There is confusing information about what is implemented and what isn't. I would expect uses of builtins etc. in the Introductions to link to their detailed reference sections. There are no breadcrumbs to help jump between sections. There is some documentation on github and some on the website. Some links are broken.

I appreciate that this is a huge undertaking and am grateful for all the effort that has gone into it already. I hope this is useful as insight into what might help/prevent adoption (at least for n=1). I will continue to keep tabs on oil for the future, thank you.

[indigoviolet]

Examples of specific things I struggled with as a dabbler in shell and an oil novice:

• running an oil script with xtrace on (looks like I have to pass -x on the shebang line, can't just use shopt)
• running a series of commands with errexit (equivalent of && chaining in shell) but exit 0 the script if they failed
• there is apparently a thing called run, but I can't find documentation for it

[andychu]

Hi thanks for the feedback. The docs are definitely behind (as mentioned on the blog).

The way it works now is that there is a skeleton of the docs, but the contents of many docs are missing, so they have a pink warning at the top. I think that page has a similar structure to what you want.

But to avoid hitting the pink warnings all the time, I put the docs that are done at the top level: https://www.oilshell.org/release/0.9.7/

(I'll probably move all the benchmark / test stuff to a different page)

I think we have the start of everything you list, except the builtin reference, which is #388. Someone else mentioned that recently as well, so I agree it's important.

---

Oil definitely isn't done and some recent blog posts try to give people a sense of where it's at:

http://www.oilshell.org/blog/2021/12/backlog-assess.html

---

Also feel free to join Zulip and ask questions. That is the best way to prompt me to update the docs. I often answer there, and then copy the answers into the docs.

What I will do is make this clearer on the home page -- there is an #oil-help Zulip channel (that most people don't know about right now).

---

For the specific issues:

• shopt --xtrace works ? Can you give an example?
  • (In shell it's set -x and set -o xtrace, but Oil prefers shopt`)
• Can you tell me where the run builtin appears in docs? I thought I had changed those all try, but I could have missed some.
• I am not sure why you would want to exit 0 if they failed, but you can use try --assign :st mycommand to set the status to the $st variable. And then do whatever logic you want. Feel free to chat on Zulip if this doesn't make sense

So yeah what I will do is

1. update the home page on where to get help (the docs aren't ready yet, though some of them are good)
2. Prioritize #388
3. Maybe emphasize the page that has the structure of the docs, which is incomplete. And move the test/benchmark stuff elsewhere.

Thanks for trying it!

[glyh]

For now the documentation seems scrambled and fragmented. This is really bad for anyone trying to learn osh/ysh. I would like to suggest spliting the documentation, blogs and some random unimplemented ideas so user have a clearer view.

Also, it seems like the website is customized created, I would like to suggest migrating to something like https://github.com/facebook/docusaurus . I may step in and help if that's preferred.

[andychu]

The best way to help write now is to try YSH, and when you have a problem, look for the docs

First in in doc/ref

If you can't find it, post a message on Zulip

Then I'll suggest a PR you can make. The docs are open to PRs, but it will help if you're more familiar with the project first