Revise top-level navigation and content placement

[jalehman]

The top-level navigation should be as follows [WIP]:

Legend

• (something wrapped with parens is effectively a comment)
• Italics are section headers

New Nav

• Learn
  • Environment setup
  • Hoon School
    • (add Worked Examples from /language/examples)
  • App School
  • App School II (Full-Stack)
• Guides
  • Basics (we may opt to have the basics be top-level instead of being nested under a "basics" header)
    • Distribute a Simple App (/userspace/apps/guides/software-distribution)
      • (this should be a folder with the contents of the above guide in its index.md)
      • Glob: Packaging Frontends (/userspace/reference/software-distribution/glob)
    • Parsing JSON (/language/hoon/guides/json-guide)
    • Remote Scry: Reading the Namespace (/userspace/apps/guides/remote-scry)
    • Fetching a Remote HTTP Resource (/system/iris/examples/example)
    • Setting Timers (/system/behn/examples/example)
    • Parsing Text (/language/hoon/guides/parsing-text)
  • Example Apps
    • Serving a JS Game (/userspace/apps/examples/serving-a-js-game)
    • Monitoring Ship Activity (/userspace/apps/examples/ship-monitoring)
      • (broken links in the first paragraphs to Urbit IDs)
    • Hosting a Website (/userspace/apps/examples/host-a-website)
      • (broken links in the first paragraph to Urbit IDs)
    • (move the contents of /userspace/apps/lightning-tutorials into guides)
      • (also verify that these guides actually work: feel free to punt on this until post-reorg)
  • Command Line (dojo)
    • Writing Generators (/language/hoon/guides/generators)
    • Building Command-line Apps (/userspace/apps/guides/command-line-apps)
    • Reverse Polish Notation CLI App (/userspace/apps/examples/building-a-cli-app)
    • Styling Text (/userspace/apps/examples/styled-text)
  • HTTP Server (eyre)
    • Handling Authentication (/system/kernel/eyre/guides/guide#authenticating)
    • Managing CORS Origins (/system/kernel/eyre/guides/guide#managing-cors-origins)
    • Using Channels (/system/kernel/eyre/guides/guide#using-channels)
    • Reading the Namespace over HTTP (/system/kernel/eyre/guides/guide#scrying)
      • (note: this section references graph store, needs to be updated)
      • (note: @midden-fabler is working scry over http right now, his work might lend itself to a guide here)
    • Handling HTTP Requests from Agents (/system/kernel/eyre/guides/guide#agents-direct-http)
    • Running Generators via HTTP (/system/kernel/eyre/guides/guide#generators)
    • Using EAuth (/system/eyre/guides/eauth)
    • Working with Noun Channels:
  • Communicating Externally
    • Orchestrating Urbit from Unix (/system/khan/examples/example)
    • Talking to External Processes (/system/lick/guides/guide)
  • Filesystem (clay)
    • Writing Marks (/system/clay/guides/marks/writing-marks)
      • (embed the contents of /system/clay/guides/marks/examples directly into this guide)
    • Using Marks (/system/clay/guides/marks/using-marks)
  • Threads
    • How to Write Threads (/userspace/threads/tutorials/basics/fundamentals)
      • (make this and the contents of bind, input, etc. into one big file)
    • (Move contents of /userspace/threads/examples here)
      • (Poke Agent uses graph-store, which is dead. This needs to be rewritten)
    • Using Threads over HTTP (/userspace/threads/examples/guides/http-api)
  • Markup
    • Writing HTML with Sail (/language/hoon/guides/sail)
    • Using Udon: Urbit-flavored Markdown (/language/hoon/guides/udon)
  • Developer Tools
    • Using the Debug Wrapper(/userspace/apps/examples/debugging-wrapper)
    • Unit Testing (/userspace/apps/guides/unit-tests)
      • (Potentially merge with /userspace/apps/guides/aqua-tests)
  • Kernel Development
    • Writing Jets (/system/runtime/writing-jets)
• Reference
  • Standard Library
    • (many things here)
  • Hoon
    • Style Guide
    • Data Structures
      • Strings (/language/hoon/guides/strings)
      • Vases (/language/hoon/guides/vases)
      • Sets (/language/hoon/guides/sets)
  • Agents
    • Docket File (/userspace/reference/software-distribution/docket-file)
  • Threads
    • Spider API (/userspace/reference/spider-api)
    • Strandio (/userspace/reference/strandio)
  • Kernel
    • (move everything under /system/kernel here, subject to specific exceptions enumerated elsewhere)
    • (eliminate any "reference" subheaders by lifting content in "reference" directories up a level)
  • Runtime
    • (move everything under /system/runtime here, exceptions below)
    • (rename "Using conn.c" to "conn.c", make top-level, e.g. no nesting)
    • (no more "Guides" section)
  • Azimuth
    • (move everything under /system/identity here)
  • Nock
    • (move everything in /language/nock here)
• Manual
  • What's currently called "Manual" or "Operator's Manual"

[tinnus-napbus]

It is much more annoying to have to figure out whether what you're looking for is a guide or a reference than to figure out what part of the system it pertains to. The latter is self-evident and the former requires mind-reading.

The original docs site was structured around the system, then Tim had it in his head the site should be divided between guides, tutorials and reference, so I restructured everything and it sucked, so I restructured everything back again to being organised around the system with guide/reference divisions beneath that. Now you want to restructure back to guides/references again.

"Snip snap snip snap you have no idea the physical toll three vasectomies has on a person"

[sigilante]

• how to rename a file (++space:userspace)