New docs structure

[DavidWells]

TLDR:

Proposed new docs structure.

Discussion:

This is the proposed doc structure. Let me know your thoughts.

Option 1

README.md # Docs intro and index
/workflow # Getting started / Dev flow
    1_Installing Serverless
    2_Creating Services
    3_Deploying Services
    4_Invoking Functions
    5_Removing Services
    6_Installing Plugins
    7_Creating Plugins
    8_Building provider integrations
    Working With Teams

/concepts # Core serverless concepts
    Services.md
    Functions.md
    Events.md
    Resources.md
    Stages.md
    Plugins.md

/examples # Examples by provider, format [provider]/[example-name]/[language]/[code]
    /aws
        /hello-world # links to Azure/Google hello-world if exists
            /node # node version
            /python # python version
            /java # java version
            /go # go version
        /dynamo-db
        /web-api-cors
        /web-api-custom-headers
        /s3-file-processing
        /etc
        README.md # Index with description of all examples
        setup.md # setup/config
        aws-events.md # Events in AWS
        What else? resources management?
    /azure
        /hello-world
            /node
            /php
            /py
        /web-api
        README.md # index
        events.md # List of Azure events
        setup.md # setup/config
    /google
        /hello-world
        README.md # index
        events.md # List of Google events
        setup.md
    /openWhisk
    /webtaskIO

Claudiajs and gordon do a great job with their examples.

• https://github.com/jorgebastida/gordon/tree/master/examples
• https://github.com/claudiajs/example-projects

I'd like to follow the claudiajs approach and categorize the examples like they do https://github.com/claudiajs/example-projects#background-processing

Also note that these docs will be published on the next site and the folder structures + filenames are going to be routes on the site.

example: serverless.com/docs/concepts/plugins

[DavidWells]

OR we have /providers at the top level instead of /examples like so:

Option 2

README.md # index
/workflow
    1_Installing Serverless
    etc.

/concepts
    Services.md
    etc.

/providers
    /aws
        /examples
            /hello-world # links to Azure/Google hello-world if exists
                /node # node version
                /python # python version
                etc.
            /dynamo-db
            etc.
        README.md # Index with description of all examples
        setup.md # setup/config
        aws-events.md # Events in AWS
        What else? resources management?
    /azure
    etc.

[DavidWells]

Option 1 urls on the site will look like: serverless.com/docs/examples/aws/hello-world/node Option 2 urls on the site will look like: serverless.com/docs/providers/aws/examples/hello-world/node

Option 1 means all examples will live in a master /examples/ folder.

• /examples/aws/
• /examples/google/
• /examples/azure/

Option 2 is cleaner from url perspective but it means the examples will be broken up into different sub folders.

• /providers/aws/examples
• /providers/google/examples
• /providers/openwhisk/examples

[pmuens]

Great. Thanks for the Writeup @DavidWells

I like proposal 2 as it's explicit about providers and signals that we're about to support multiple providers pretty soon.

I'd also include this issue in the discussion: https://github.com/serverless/serverless/issues/1522

This is something @eahefnawy and @ac360 came up with a while ago (taken from the issue above):

Quick Start:

Concepts:
   - Services
   - Functions
   - Events
   - Resources
   - Plugins

AWS:
   - Functions
   - Events
     - S3
     - Schedule
     - HTTP
   - Resources
   - Environment
     - Stages
     - Regions
     - Vars
   - Workflow
   - Examples
Azure:
  - ...
Google:
  - ...

Contributing

About

[mthenw]

+1 for Proposal 2.

Two things about /workflow part:

1

This will be first section that every user will read so maybe we should make it as simple as possible. I'm not sure if creating plugins and building provider integration are topics for getting started. What do you think about making it shorter like this:

/getting-started # Getting started / Dev flow
    1_Installing Serverless
    2_Creating Services
    3_Deploying Services
    4_Invoking Functions
    5_Removing Services
    6_Installing Plugins

and adding another section

/advanced # Advanced topics
    1_Creating Plugins
    2_Building provider integrations
    3_Working With Teams

2

IMHO /workflow should be renamed to /getting-started. When you start typing url in the browser it should be easy to find this page and the url should be the same as title.

[Jorenm]

+1 for proposal 2. Also I agree with mthenw that separating the frequently accessed basic functionality from the more advanced is a good idea.

I'd also like to see a Troubleshooting section added for some common causes and solutions to errors like the "UPDATE_ROLLBACK_FAILED state", or "The specified bucket does not exist". My solution to all such errors was to delete my stack from Cloud Formation and redeploy.

[DavidWells]

Updated structure/layout can be seen on this branch: https://github.com/serverless/serverless/tree/newDocsSetup/docs

The updated structure looks like:

/docs
1_step_1.md
2_step_2.md
etc.md
  /providers
    /aws
    README.md # index about AWS
      /examples # want to get to lots of examples like: https://github.com/claudiajs/example-projects
      README.md # index listing all examples
        /hello-world
          /node
          /python
          /java
        /example-2
    /azure
    /google

We took @mthenw idea and then decided to merge all those docs in the top level of docs in order of when they should be read.

---

@pmuens The providers are all broken down into their own folders: https://github.com/serverless/serverless/tree/newDocsSetup/docs/providers/aws. I'm curious to hear your thoughts on how we should display Resources, Events, etc from providers.

Right now we are showing all of that information in a single top level index file and I'm wondering if this will scale or break down eventually

---

[pmuens]

Hey @DavidWells thanks for that! Just added some comments in the PR (much of those apply for the whole PR).

Here are some other thoughts:

• IBM OpenWhisk is missing in the doc about providers
• I would remove the guide character of the docs so that each document is standalone and don't has / need any context. So if I want to know how to deploy I just look into the deploy command doc and see a simple explanation without prosa text (maybe we can even include all of those commands into one large doc file)
• We need to check all the describe lifecycle events so that we don't have inconsistencies there.
• I like the per provider directory approach but would add separate docs for events and resources and link to them with the help of a "Table of contents" section in the providers index file
• IMHO the main README.md for the docs needs a table of content which links to the corresponding .md files
• Just a cosmetic one but I would rename 9_working-with-teams.md to 09-working-with-teams.md so that the docs are alphabetically sorted and everything has a - rather than a mixture of _ and -

[pmuens]

Just revisited the structure and here's my proposal (TOC = Table of contents).

---

# Documentation

- 00-README.md                      (TOC, Quickstart, FAQ, Contributing)

## Quickstart / Guide

- 00-README.md                      (TOC)
- 01-installation.md
- 02-provider-account-setup.md
- 03-creating-a-service.md
- 04-deploying-a-service.md
- 05-invoking-a-function.md
- 06-removing-a-service.md

## Basics

- 00-README.md                      (TOC)
- 01-services.md
- 02-functions.md
- 03-events.md
- 04-resources.md
- 05-plugins.md
- 06-serverless-yml.md
  - How all those discussed parts are used in Serverless
  - Variable system

## Providers

- 00-README.md                     (TOC)

### Amazon Web Services (AWS)

- 00-README.md                      (One large example serverless.yml file + TOC)
- 01-api-gateway.md
  - Simple event config
  - Advanced event config
  - Default request / response templates
  - Adding an own request / response template
  - CORS
  - Custom authorizers
  - API keys
  - HTTP proxy setup
- 02-s3.md
  - Simple event config
  - Advanced event config
  - Setting up a bucket
  - Using an own bucket
- 03-schedule.md
  - Simple event config
  - Advanced event config
- 04-sns.md
  - Simple event config
  - Advanced config
  - Using an existing topic
- 05-kinesis-streams.md
  - Simple config
  - Advanced config
- 06-dynamodb-streams.md
  - Simple config
  - Advanced config
- 07-iam.md
  - Adding custom IAM role statements
- 08-custom-resources.md
  - Adding own CloudFormation resources
  - Overwriting existing resources
- examples
  - example-1
    - serverless.yml
    - handler.js
    - README.md
  - example-2
    - serverless.yml
    - handler.js
    - README.md

## Extending Serverless

- 00-README.md                    (TOC)
- 01-writing-a-plugin
- 02-provider-integration-through-plugins.md
- 03-serverless-behind-the-scenes
  - Explain lifecycles
  - Explanations how e.g. resource merging works

---

## Misc

- usage-tracking.md

---

Key Takeaways:

• Flat structure
• Guide which shows how a development workflow looks like
• Some basics so that one understands what the different parts of Serverless are
• Providers with their events (structured in a way the user is already familiar because of the providers functionality)
• Docs to understand how one can work on the framework (and how it works behind the scenes) --> More contributor oriented
• Misc section for everything else which does not directly fit into the other categories

/cc @serverless/core

[flomotlik]

@pmuens I like this a lot. The only addition I would do is examples in an examples subfolder of the provider. There we can do a few more complex examples to show interaction of a few things. Other than that I like this a lot!

Especially making everything so easily searchable on the overview pages

[pmuens]

Thank you!

Just updated my comment above with the feedback from @flomotlik.

[davidroman0O]

I hope to see the full documentation asap 😄

[flomotlik]

@warka0 all in a new branch and PR: #2002

[davidroman0O]

@flomotlik Thx for notifying! 😄

[wmarra]

Hi there, the new documentation is staying smooth and more easy to understand the flow. More examples was really good @pmuens and @DavidWells, I'm new on serversless and that was my first doubt. Now I understand more about the flow and what we can do with serverless, by the way I'm now creating a lambda functions to manage queue and extending the resources on cloudFormation, everything managed with serverless. This is awesome!