Reorganizing the documentation to separate "Bref for web hosting" and "Bref for functions"

[mnapoli]

Following many exchanges and support requests over the months, as well as the fact that native events are better supported by Bref, it could be good to reorganize the documentation to separate:

• running PHP as usual (PHP-FPM, frameworks, etc.) on Lambda
• running PHP functions in the "AWS Lambda" way

In the first use case, we use Lambda for (scalable, cheap, effortless) web hosting.

In the second use case, we use Lambda to build event-driven serverless applications using functions.

Naming is hard, but here are possibilities for the 2 "main sections" of the documentation:

• Bref for web hosting
• Bref for functions

Thank you @GeeH for coming up with that!

The last one could also be Bref for event-driven applications but I find that more confusing, and it's a mouthful.

Goals

• Users should more easily understand that there are 2 main use cases for Bref: web hosting and functions. They should know easily which one they want to use. They should also be aware that the other exists.
• AFAIK there are 2 main categories of users: those that know about Lambda and want to write functions in PHP, and those that don't and want to benefit from serverless. The first one should easily land on "Bref for functions". The second one should easily land on "Bref for web hosting". This is why I think "Web hosting" should be first in the list. It should be the default Bref use case, both in documentation and bref init. Those that know about Lambda will find their way for easily.
• "Web hosting" goes hand in hand with frameworks. That means that Laravel and Symfony should be clearly visible.
• When a user has a specific use case or problem in mind, they should find the solution easily via the menu That means that pages should be structured mostly around use cases (local development, deploying assets, using databases, etc.). The exception I see is the reference regarding serverless.yml, which is useful.
• Users should be able to follow the documentation linearly That means: ideally the documentation should build over what was explained previously. For example, we should not explain how to deploy before users have something to deploy.

Proposal

Here is a 1st proposal, feedback is welcome:

The design is not set in stone of course, this is a first attempt that iterates on the current design.

[mnapoli]

Something I forgot to mention: I separated the Deployment page because it is common to both use cases. However, it will be weird that it gets mentioned afterwards.

What I suggest is:

• both "Bref for web hosting" and "Bref for functions" should explain to deploy with serverless deploy, straight from your machine (i.e. light introduction to deploying the app)
• the Deployment page should explain how to do a "proper" deployment, with CI/CD

That way we mimize the duplicated content, and we keep a logical order of things.

[GeeH]

This looks fantastic, and I'm excited to help and get started. How can I help?

G

On Mon, May 4, 2020 at 10:18 AM Matthieu Napoli notifications@github.com wrote:

Something I forgot to mention: I separated the Deployment page because it is common to both use cases. However, it will be weird that it gets mentioned afterwards.

What I suggest is:

• both "Bref for web hosting" and "Bref for functions" should explain to deploy with serverless deploy, straight from your machine (i.e. light introduction to deploying the app)
• the Deployment page should explain how to do a "proper" deployment, with CI/CD

That way we mimize the duplicated content, and we keep a logical order of things.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/brefphp/bref/issues/641#issuecomment-623352993, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAEVYACNOSZQDVRZLN56C33RP2B7PANCNFSM4MYSXTNA .