Simple suggestions for better docs

[Gawidev]

Hello, been enjoying yq as someone entirely new to yq and jq. There are a few things I've noted during the learning process that could hopefully be valuable. I believe there are a few simple changes that could be done to the docs to make them much more intuitive and helpful.

1. Ordering operator doc pages by how common/important they are
   • The page about Traverse (read) says "This is the simplest (and perhaps most used) operator." yet is all the way at the bottom due to alphabetical ordering. I feel getting a good sense of how the program is used could be made a lot easier if the operators one might use most often were the most visibly accessible.
2. Adding aliases and operator syntax in page titles
   • This would help quickly recognize parts of the structure in different recipe snippets from the documentation examples, the github discussions and elsewhere. The simplest way I can think of doing this would only require a small change from the way the titles are currently structured, so any non-obvious yq syntax elements are still visible at a glance.
   • eg. something akin to:
     • Recursive Descent/Glob (..,…)
     • Boolean Operators (or,and,any,all)
     • Tag (type)
     • Assign/Update (=,|=)
     • Alternative/Default (//)
     • Document Index (di)
     • Anchor & Alias (explode)

These are just ideas that could bring benefit to new users without requiring complicated changes to the docs. Regardless, thanks for this tool, it's been a joy to discover 🙂.

[mikefarah]

Good idea, will look into it