Synced w/ examples + explanation improvement-- up to security-driver.md

[mattlevan]

PR for everything in /developer/arvo/docs except internals/*, security-driver.md and api.md as I'm working on fixing arvo #442 first!

[xykj61]

Cool, this helps -- thanks man! There are small little things still left to fix here to get this ready for the retrofit/remaint breach coming up, which includes some new Hoon/Zuse syntax and the new Urbit developer docs. I'll try and get all of this in a Fora post in a call for doc contributions to get everything up to date.

But, for now, here are a few things I just noticed from a quick glance over that still need updating for this to be merged:

1. Navhomes need to end in a /

Basically, if the Tree YAML metadata option for navhomes doesn't end in a slash, it makes relative links work really weird. So instead of navhome: /developer/docs, it should be navhome: /developer/docs/ for everything under /developer/docs/. Which brings me to the next point:

2. Slight directory structure change

The idea here is to separate technical tutorial/reference doc from "Using" and "About" guides/pages. So instead of everything being under /developer/docs, I've split things into:

• /developer/community
• /developer/about/
• /developer/using/
• /developer/docs/

Link to things accordingly. When in doubt, load the updated docs into fake ~zod with the develoepr docs copied in and test the links yourself.

Then the last step would be:

3. Get everything to work on the retrofit/master urbit and arvo branches

We'll probably wait to deploy these docs until we breach, so it's fair to start updating these to the new syntax for Hoon 143 and new Zuse.

The most notable Hoon 143 changes are the new mold syntax. {a/@ b/*} is now [a=@ b=*], and ++ foo $bar-mold is now += foo $bar-mold (++ general dry arms to += mold-specific arms).

Then there's new Zuse. Look in /lib/old-zuse on Arvo master to see the mappings from old (maintenance) Zuse arms to new Zuse arms. In the docs and examples that use these affected Zuse functions, just find and replace to the new binding in /lib/old-zuse verbatum for now, i.e. bowl to bowl:gall, prey to prey:pubsub:userlib, etc. We can figure out later if we like the namespacing function-calling style versus using something more concise via the liberal use of =,'s, for examples (Curtis is working on a blog/Fora post highlighting the new syntax which will include these new runes as well as the interface for doccords).

So, I'd say make the small relevant changes that you can @mattlevan -- otherwise, keep working on the security driver, API and internal docs a bit more. Keep in mind -- those all need some serious work and might be pretty hard -- don't hesitate to ask questions or let us know when you're struggling with something.

[mattlevan]

Awesome, thanks for the speedy feedback @keatondunsford! I have noted the new directory structure (the links in the PR are good to go) and fixed the last navhome that I missed the trailing / on.

These are my priorities:

1. Fix whatever's wrong with GitHub OAuth2 driver
2. Work through api.md
3. Submit new PR
4. Work through internals
5. Re-sync code blocks with examples (provided they're updated to comply with new %zuse)
6. Probably add in some snippet about how to use doccords in basic.md so readers can utilize them throughout the arvo docs

Keep on keeping on! Thanks again for the assistance. Cya in meta.

[mattlevan]

Closing this as #212 overrides.