We’re constantly trying to perfect our documentation, however due to the speed of development, some features and aspects of Serverless development are left behind, and we’re always making an effort to keep it on track.
Best on your experience, what do you think we should add to our docs? Whether that’s new features that we forgot to cover, or simply guides that you think will be really helpful. And do you think our docs navigation structure makes sense and easy to follow? If not, how would you structure it instead?
Would you love to have more guides which will show you how you can build applications but won’t go into depth or more “isolated documentation” about a specific functionality with all it’s features?
You’re totally right! That’s what I had in mind as well. Our blog is pretty minimal at this point and we’ll add much more features in the future. (we’re discussing maybe moving to Medium!)
I’d love to see some info on the context vs the callback. For instance, the difference between returning the callback or calling context.done. Examples of code in general is appreciated - - like handling POST and query parameters.
What you think about AWS docs? Do you think we should cover some guides about using Lambda so that you wouldn’t need to get back to AWS docs? We’re currently relying on the user’s ability to get through AWS docs.
TBH, their docs are OK, but you probably don’t need to repeat their stuff. it would be good to at least reference it. There are a lot of metas to wade through in the serverless landscape, just pointing to the AWS docs to say “learn about the function structure here” would be really useful.
agreed for sure! They’re already covering a lot of stuff. I’m thinking maybe we could just offer some tuts or guides on how to do specific AWS things on Serverless
+1 for tutorials and guides. I think that’s more important initially and replicating the docs would be a waste. Tutorials and guides that link to AWS docs allow developers to learn concepts and then dive deeper into the AWS docs once they’ve gotten started.
The AWS docs are dense. They contain a lot of information and are hard to understand initially. Though once you have your head around the concepts, the docs become extremely helpful.
The same will apply with Azure, Google Cloud functions ect.
As someone who only arrived at the project today, I am very excited to use serverless, but I appear to have found it in a state of transition. The website has what appear to be v0.5 instructions, and the repo has 1.0beta instructions, but no details about what’s been deprecated. For instance, the concept of being able to generate a project appears to have been deprecated in favor of a ‘every service is a template’ model. I never read that, I just had to piece it together from the two sets of docs and a few error messages when create project didn’t work.
What would be really helpful is a few details on how we should be structuring and initializing services, especially ones that are designed to work together. In the previous version, it seemed clear that if I wanted to create a REST API project (which I do) and wanted each of my endpoints to be a service, I could create a folder structure within my project and deploy updates to each piece as needed or the project as a whole.
Now if I want to create my REST API, do I use nested folders? Do I make individual templates/repos for each possible endpoint called modelNameCreate, modelNameUpdate, etc? Should I be running npm init myself, or did I miss a step? What should my .gitignore look like so I don’t accidentally deploy generated files that are only relevant to serverless. Here the v1 docs don’t offer any guidance. And since the previous docs are still prominent on your website, it’s a little confusing for a newbie trying to make their first baby steps which direction to go.
That all said, I’m really excited about the project, and can guess that some of the above is slated to be resolved in beta 2. Just wanted to let you know what the experience was of someone coming to it cold.
Would be good to get some v1 examples and recommendations of file structure/boilerplate for more advanced real world projects with multiple services (or does everything live under one service?), multiple functions, endpoints, methods per endpoint, node modules, shared logic/libs, binaries, etc…
I would second what @dehuszar is saying. I have also arrived at serverless in the last couple of days and it’s been a little bit confusing figuring out which docs to follow. Now that I’ve got that sorted, installed the latest beta, and deployed my first service I want to delve deeper and build some more complex stuff.
A few tutorials/best practices for the layout/structure of a service would really help with that. Maybe some common use cases, eg. CRUD using dynamoDB or SNS messaging would be a good place to start?
There seems to be lots of good stuff happening here, which is awesome, and I’m excited to see where this project goes
I would like to 3rd what @dehuszar and @pointless_cog. I started working on the project this past weekend and had trouble finding the docs that matched V1. The examples did not match up to what I was seeing. I would suggest having a toplevel docs that branch off to respective versions .5 and V1.
Also, I received a weird subscription error from AWS when I attempted to deploy (not subscribed to service). I ended up creating a new account still received it. When I used SLS Logging, the logs were ambiguous. I know it’s but it would be helpful to answer some of the issues that we may encounter when attempting to use the serverless functionality. Just some suggestions
A good sample project like the boilerplates in v0.5.* would be great.
As mentioned by others before, this is what is a bit confusing at the moment:
multi-service/function project
when exporting code to a “lib” folder (which is the recommended practice in 0.5) can be confusing. An example would help
node modules. Where do I install them so they can be accessed from my endpoints/lib folder?
how to wire up endpoints in serverless.yml if it is not located at the root of the project/service?
All of this could be answered with a slightly more advanced template than the existing one
Great stuff though. I really love the way this project is going, and I have to say that, contrary to a lot of open source projects, this one feels really welcoming. So well done getting the community going and creating such a good atmosphere
Just starting with v1, I have some experience with 0.5 and trying to figure out all the changes.
Given the ongoing development of v1 its been quite a challenge to get all the informations I was looking for from the documentation.
The new structure of Serverless is neat; yet until you figured it out it is quite difficult to understand where to look for the informations you need (especially in GitHub).
I think a couple of things would have speed up my discovery:
(and more important) as already suggested, step-by-step tutorials based on real user/developer stories would help a great deal in both learning the tech and discovering new interesting/non obvious features as well as suggesting well thought best practices.
For more help here is what I tried to do:
I decided to go full serverless for a new project I’ll be starting soon. I wanted to know (in no particular order/importance):
How do I create an API with url parameters?
How do I use custom authorizers/auth0?
Is it better to have a custom authorizer or have authorization logic baked into the lambda?
Can I serve a react based SPA from lambda?
How do I make various team work on different lambda and yet serve the whole API from one endpoint? Is it a good thing or should I have an “aggregation” API in front of the other specific APIs?
Can i dry run my deploy to see what the CloudFormation file is going to look like? Can I edit it manually?
I managed to answer almost all those questions myself but it took me the best part of a day and quite some digging
I’d love to see a v0 vs v1 section in the documentation to help better transition over. In it’s current state there’s on easy way to migrate over because the v1 docs aren’t complete and there’s a significant difference between both versions that it’s not as intuitive as might be assumed.
