-
Notifications
You must be signed in to change notification settings - Fork 197
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation overhaul for v2 #527
Comments
A few more ideas: Suave is also nice to use with Suave.Oauth and Logary. Maybe it needs a section for authentication or at least a pointer to the authentication section in the Suave Music Store. Also perhaps add a section for web security concerns like CSRF, OpenSSL, certificates, etc. |
@scitesy Updated the list |
I also thinks this looks great. Maybe an explicit section about webparts and combinators. It should explain how to write a basic combinators from scratch to five users a better understanding of what you can do with suave. This could be "baked" into one of the other parts of the docs, but an explicit entry will make it easier to find it. |
Suave is also nice to use with Topshelf. :) I'm currently working through an input validation / error handling story in our Suave project at work. That sort-of fits with mastoj's suggestion of a combinator-from-scratch workbook, and might make a good motivating example. |
How about having a sandbox environment "TrySuave"? The User can define the WebPart in an editor, Define the request (we can provide a user interface like Postman) and see it in action? Requires lot of effort from our side though but I feel it's worth having! |
It's a nice idea to have documentation based on concepts (logging, authentication, etc.,). While documenting we need to provide a real world example. |
@tamizhvendan You and I should create some videos for each section. Get the low hanging fruit to make it easier for people to get up to speed with Suave. Then we see what people are struggling with or where other think there could be some improvement and we can then focus in those areas. |
I would like to see a greater effort around:
|
@monkieboy on what level do you want to see a greater effort around Suave+Fable? Re-use of models? I've been playing with the idea of having isomorphic html dsl for both Suave and Fable, but there are a lot of problems associated with that. So if you were thinking a long those lines I probably think that is out of scope, but it would definitely be nice to some use cases with apis in Suave and the re-use of the model and types in fable. |
I was thinking mostly about use cases, making the barrier to entry as small as possible by providing (small initially) examples. |
All that you're saying makes sense guys. Divide the work; e.g. by creating an issue per section and claiming it. Docs are in I've updated the static file handling docs tonight https://suave.io/files.html |
@tamizhvendan I've added your suggestions to the large list. |
By the way; you're documenting a web server that can do almost anything; let your imagination run free and make the docs fun when you write them! We can host almost any backend system, too, like EventStore if you want to showcase some part of F# through that. |
@haf between this link (https://suave.io/Suave.html) is no longer pointing to the auto-generated API docs. |
I know, somewhere a few commits ago, @polytypic's doc generator broke down, so it's currently suspended... Just running the rake task for it reproduces its error, so it's easy to reproduce. |
How's it going everybody? :) I just corrected the docs for socket bindings. |
One thing that is not directed related to Suave but would be helpful to be in the docs is to have a project setup section where you integrate with Brunch/Webpack for building static assets, hot reloading of F# files, etc... |
Is there any way to view the API documentation yet? Trying to learn Suave but it's very hard since I only can finde scattered snippets across the web. Many of which seem outdated. |
Can you solve #536 (comment)? Then I can push the update. The API docs is the generated docs. |
Hi all, With the help of @theimowski, I came up with a git book version of current suave documentation. One major advantage I am seeing in this approach is, we are getting the nice formatting from git book and tooltips in the code snippets This tooltip will help the reader to know the namespaces and modules directly. Looking forward to knowing the feedback and how can we take it from here? |
Thank you for your patience. I really appreciate the work you've done. The docs need to be part of our web site with Suave web site styling for me to point everyone and everything to them. Having a gitbook is nice, but we need to have the branding there, or the docs won't work. |
Good evening everyone. I was directed to this issue as one of the good ones for beginner open source contributors. However, I have no idea about what Suave is? Is this a wrong project for me? Or can someone please kindly put me through? Thank you very much everyone |
Let's sketch out some ideas for the documentation overhaul for v2 of Suave. This issue tracks creating a new web site that guides people towards being proficient at writing Suave code.
Suggested structure:
EventSource
modulewarbler
/request
/context
Also:
The text was updated successfully, but these errors were encountered: