Documentation overhaul for v2

[haf]

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:

• Home page – single scrolling page, served by server
  • Quick intro

    Suave is a simple web development F# library providing a lightweight web server and a set of combinators to manipulate route flow and web part composition.

  • A counter that updates live, on how many browsers are connected using the EventSource module
  • Three 'concepts' with illustrations
    • functional – shows Hello World
    • stand alone
    • cloud / micro-services ready – Heroku, Kubernetes, Azure Functions links
  • CTAs (with sublinks – expand on click?)
    • Learn
      • Walkthrough
      • Suave music store
      • F# Applied
    • Go to community
      • gitter.im
      • github / github issues
      • twitter.com/suaveio
    • Commercial support
      • Commercial support providers, e.g. Mark Grey?
  • Walkthrough
    • Outline – showcase e.g. FsSnip including how it's hosted
    • How to set up VSCode and .Net Core for Suave.IO usage, with screens/animated gifs
    • Hello world (repeated)
    • Filters – e.g. path, pathScan
    • Testing your app so far with Suave.Testing
    • Files
    • Deferring execution with warbler/request/context
    • Building HTML on the server with Experimental
    • EventSource
    • WebSocket
    • Setting up log shipping, tracing and metrics with Logary
    • Deploying to google cloud and Kubernetes
    • Writing Azure Functions

• Nice to use with (tm)
  • Fable
  • Fable + ReactJS/webpack
  • OWIN
  • Suave.Swagger
  • Suave.Hawk
  • Suave.Locale
  • Suave.OAuth
  • Logary
• Concepts
  • Security
    • CSRF
    • Authentication; basic, hawk, oauth, claims
    • Authorisation
    • TLS
  • Logging
  • Redirects
  • Input validation & form binding
  • Reverse proxying
• Contribution guidance
• Sites using Suave
• Testimonials
• Videos
• Blog Posts

Also:

• It would be great if each page had a link to itself in this repo, to allow quick changes
• ...

[scitesy]

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.

[haf]

@scitesy Updated the list

[mastoj]

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.

[MattJOlson]

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.

[tamizhvendan]

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!

[tamizhvendan]

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]

We can separate sections for

• "Sites using Suave"
• "Testimonials"
• "Videos"
• "Blog Posts".

I feel it would be nice to have a donation page. @haf and @ademar deserve it!

[monkieboy]

@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.

[monkieboy]

I would like to see a greater effort around:

• Suave+Fable
• A better explanation around choose and the combinatory flow of webparts (I will write it as I understand, and you can validate that it is as accurate as it will be descriptive and easy-to-understand)

[mastoj]

@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.

[monkieboy]

I was thinking mostly about use cases, making the barrier to entry as small as possible by providing (small initially) examples.

[haf]

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 ./docs.

I've updated the static file handling docs tonight https://suave.io/files.html

[haf]

@tamizhvendan I've added your suggestions to the large list.

[haf]

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.

[ademar]

@haf between this link (https://suave.io/Suave.html) is no longer pointing to the auto-generated API docs.

[haf]

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.

[haf]

How's it going everybody? :)

I just corrected the docs for socket bindings.

[imetallica]

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...

[johanvts]

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.

[haf]

Can you solve https://github.com/SuaveIO/suave/issues/536#issuecomment-289215305? Then I can push the update.

The API docs is the generated docs.

[rmunn]

@haf - #615 should solve #536.

[tamizhvendan]

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?

[haf]

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.

[ghost]

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