[arc.codes] Documentation Outline

[macdonst]

Notes:

• New document structure:
  • Top-level docs
  • Category
    • Category-level docs
    • Group
      • Group-level docs
      • Hidden group-level docs (see: Setting up a domain sub-docs)
• about/mission doc to be subsumed by The Architect Way

---

• Home (not in the nav)
  • > Welcome
  • > Installation
  • > Get started

---

Side Navigation

• Introduction

• The Architect Way
  • > Excellent developer experience
  • > Cloud function-centric development
  • > Local, offline development // note: possible to work online with real infra
  • > Code sharing across functions
  • > Automated dependency management
  • > Discrete environments
  • > Declarative deployment
  • > Runtime resource discovery
  • > Optional helpers
  • > Secured to least privilege by default
  • > Incremental enhancement? development?
  • > Open source and open governance
  • > ¿Comparison to other frameworks?

Get started

• Quickstart // link to AWS tutorial
• Project manifest format
  • > Overview
  • > Architect format
  • > JSON
  • > YAML
  • > TOML
• Project files & folders
  • > Overview
  • > Creating new resources & files
  • > Special files & folders
  • > Custom paths

App development // alt name: App development guides

• Developing with cloud functions
  • > Overview
  • > Principles & key concepts
  • > Using cloud function middleware // how & why
• Function dependencies
  • > Overview
  • > Updating dependencies
  • > Hydrating dependencies
  • > Dependency management
• Code sharing across functions
  • > Principles
  • > Shared
  • > Views
• Building HTTP & WebSocket routes
  • > Overview
  • > HTTP routes
  • > WebSocket routes // should probably include / have a section for connecting to WS
• Using HTTP & WebSocket sessions
  • > Overview
  • > HTTP sessions
  • > WebSocket sessions
• Building async events & queues // aka background tasks
• Building scheduled tasks // cron should be in the metadata
• Managing environment variables
  • > Overview
  • > Architect environments // testing, staging, production
  • > Local environment variables // prefs.arc + .env; when they are synced vs. not synced
• Using static assets
  • from Add doc for asap templating in public assets #427 ${STATIC('file.png')} and ${arc.static('file.png')}
• Working locally / offline
  • > Overview
  • > Initializing new functions // arc init, preferences
  • > Environment variables // prefs.arc + .env
  • > Previewing // localhost:3333
  • > Testing HTTP routes & endpoints
  • > Testing events & queues // future: add queues, scheduled
  • > Testing database tables & indexes
• Debugging your app
• Logging & monitoring your app

---

Tutorials

• Going beyond "Hello World"
  • > Static assets + CNDs
  • > Database tables
  • > Environment variables
  • > CI/CD
  • > Event functions
  • > Scheduled Functions
  • > Queue functions
  • > Macros
• Setting up a domain
  • > Overview
    • Route53
    • Route53 & CloudFront
    • Dreamhost
    • Godaddy
    • One
    • Namecheap
• Configuring AWS
  • > Get AWS IAM credentials
  • > Minimum viable permissions
  • > Configure AWS CLI
  • > Working with multiple profiles
  • > Credentials file vs. environment variables
  • > Deploy buckets
  • > Default runtime
• Using Architect plugins // metadata: macros!
  • > Overview
  • > Installation
  • > Plugin API
  • > Helper methods
  • > Examples
  • [soon!] [ ] Modeling & persisting data
  • [soon!] [ ] Building single page apps (SPAs); include aliasing
  • [soon!] [ ] Implementing CORS

---

Reference

Project manifest

• @app
• @aws
• @events
• @http
• @indexes
• @plugins
• @Proxy
• @queues
• @scheduled
• @shared
• @static
• @tables
• @views
• @ws

Configuration

• Function config
  • > runtime
  • > memory
  • > timeout
  • > concurrency
  • > layers
  • > policies
  • > architecture
• Local preferences
  • > @create
  • > @env
  • > @sandbox
  • > @sandbox-startup

CLI

• deploy
• destroy
• env
• hydrate
• init
• logs
• sandbox

Runtime helpers

• Node.js (@architect/functions) // I can see this doc being broken up into a series of arc fns docs a level deeper, wdyt?
  • > Set up @architect/functions
  • > arc.events
  • > arc.http
  • > arc.http.async
  • > arc.http.express
  • > arc.http.session
  • > arc.queues
  • > arc.services
  • > arc.static
  • > arc.tables
  • > arc.ws
  • > Set up @architect/asap
  • > API
  • > Examples
• Deno
• Python
• Ruby

---

• Upgrade guide
• App limits // should this be automated?
• FAQ

---

About

• Mission
• Community & governance
• Contributor guide
• Playground

[tbeseda]

Do we have any plans for redirects for the large swath of URLs we are about to change?
I'm all about the better naming and organization, but it might cause 404s from places we don't control.

We already have a redirect map with ~60 paths that we could expand. Or maybe we could make a "smarter" system that looks for a similar doc name? Or maybe there's a way to pass a search term to the search widget on the front end?
At the least we need a real view for 404s.

[tbeseda]

We already have a redirect map with ~60 paths that we could expand.

For sure going to add to the existing map for known deprecated paths.
Also going to add some 404 to catchalls that don't resolve to a doc. Could be a cool place for an embedded search.