Add docs site

[davidfowl]

There should be a documentation site focused on scenarios similar to this https://gowebexamples.com/.

I'm also thinking about integrating samples from https://github.com/dodyg/practical-aspnetcore.

cc @dodyg

[dodyg]

I will be happy to work on the documentation site, port the samples over and create new samples for this.

Do you know when you are going to publish a nuget package or should the samples reference FeatherHttp.project?

[davidfowl]

I'm going to try to get it done this week. I just need to figure out the github actions fu 😄

[davidfowl]

Packages are currently available here https://f.feedz.io/davidfowl/featherhttp/nuget/index.json. I'm going to make a github pages site for it.

[RobotOptimist]

@davidfowl I thought I was going crazy - but it seems that the packages didn't upload? Let me know if I'm missing something please

PS C:\Users\jmacivor\code> nuget list -s  https://f.feedz.io/davidfowl/featherhttp/nuget/index.json
No packages found.
PS C:\Users\jmacivor\code>

[davidfowl]

Add the -pre flag to list per-release packages (it might have another flag name)

[davidfowl]

@dodyg how do you want to go about this? Do we come up with a TOC (table of contents) we like and go from there?

[dodyg]

Yes.

I think we should split the content into three categories:

• Explaining the "framework" itself especialy `WebApplicationHost.CreateDefaultBuilder(args);

  • WebApplicationHost.CreateDefaultBuilder(args); What does this bring?
  • Environment
  • Services
  • Configuration
  • HostConfiguration
  • Logging
  • Http
  • Properties

• How to do things in Feather in contrast of the canonical ASP.NET Core approach

• Various practical samples how to achieve things

  • Super slim middleware only app
  • MVC
  • Razor Page
  • SignalR
  • gRPC
  • Blazor

This is what I can come up so far while trying to juggle cooking for Christmas dinner for 12 :)

[dodyg]

This approach assumes that the people who will be trying/using Feather will have some experience with ASP.NET Core. The question is whether we should accommodate people that just starting up doing web development and try to attract them to use this much simpler approach to ASP.NET Core.

[RobotOptimist]

@dodyg I'd like to participate in this as much as I can, I'm playing around with creating a little site to display these tutorials in the style of the go site that @davidfowl mentioned: https://github.com/RobotOptimist/learn-httpfeather I'm using Nuxt and plan to use the static file generator for the web resources. Wondering if I should go ahead and register a domain or if you and David already have something in mind. I'm doing this because I want to deeply learn about what David has done here, so maybe I'd be doing this anyway - but given I have a chance to help with a need here, I'd just love to do it.

Thanks

[dodyg]

This is awesome. Let's figure out a broad outline on how these tutorials should go and their target audiences. @RobotOptimist if you have something in mind, please post them.

I am approaching this as an experienced ASP.NET Core so I am interested in contrast. Right now I am taking public notes, writing samples and making mistakes on Feather on this thread https://twitter.com/dodyg/status/1211745022263083008 as I am learning more how to operate within this framework.

I do believe though that Feather can be a very useful entry point for people new to ASP.NET Core. The boilerplates and concepts that a newcomer need to learn in order to start is less than the standard ASP.NET Core.

[davidfowl]

I think we want to aim at both audiences but we shouldn't assume people know ASP.NET Core, or even C#. I think there are 2 kinds of docs:

• Conceptual - The why behind things. Why is the framework designed this way? (the philosophical aspects of the design).
• How do I do task X - A "straight to the point"

I like the micro examples because its task based and shows you how to get started doing specific tasks immediately (copy pasta friendly). The former is fine but much less important right now.

[dodyg]

OK let's start with the absolute beginners.

We will need to write "Getting Started" tutorial:

• Where to download vscode.
• Where to download the .NET Core 3.1 SDK.
• How to run the samples. Ask the reader to run the hello world sample to make sure that they can get the environment working.

Then introduce them to the basics:

• Hello World
• How to read and write cookies
• How to get values from query string
• How to obtain value from HTML form
• How to handle upload files
• How to read from and write to HTTP headers.
• How to allow static files files
• How to return JSON output
• How to handle routes
• How to log your app
• How to change the port of the webserver
• How to use TLS
• How to show exceptions during development
• etc

Data:

• How to use it with a database (EF, Dapper, RepoDB)
• How to use it with Redis
• Etc

How to pair it with JavaScript frameworks

• AngularJs
• VueJs
• SvelteJs
• ReactJs

Application Framework:

• Razor Pages
• MVC
• Blazor Server Side
• Blazor
• SignalR
• etc

[dodyg]

@davidfowl where do you want the samples and documentation to be contributed to? Should we just do pull requests to this repository or should it be on another repository?

[RobotOptimist]

Well, I've spun up a site and set up continuous deploys to netlify using the previously mentioned repository:
https://github.com/RobotOptimist/learn-httpfeather
currently hosted, continuous deployment on master (still haven't got a domain yet, want to see if you guys want to go this way or do something else)
https://competent-hypatia-67bb77.netlify.com/

The repository has pages ready to receive the examples in pages/examples where you would put your html inside of <template></template> tags.

If it's more comfortable, I can also install a markdown parser plugin so we can write the example code in markdown.

To run it, you download the repo and then
npm install

and then
npm run dev

Ideally, I'd like to use feather HTTP to do this, so I'll be thinking about how to switch it over to that. Maybe do the vue example this way? 😀

[solev]

If you do a static export docs website, I think GH Pages is a good idea?

[davidfowl]

I was thinking gh pages as well.

[RobotOptimist]

No problem, I'll switch it to GH Pages

[RobotOptimist]

Okay, got it done here: https://robotoptimist.github.io/learn-httpfeather/
Sorry it's a bit of a mess - I'll be setting up the automated workflow this afternoon

[RobotOptimist]

Automated documentation workflow is up. I've got the first version of Getting Started on the home page also. I've also created a repository for a dotnet project template and included instructions for people to clone that repo and use that template.

[davidfowl]

@RobotOptimist it might makes sense to move the docs site to this repo as well. I have to look at turning on ghpages and setting up a domain/cname.

[RobotOptimist]

@davidfowl I understand, let me know what you need.

[RobotOptimist]

#22
@davidfowl I've created a pull request to add the static generator to the project - let me know if this is no longer desired

Also, I've been thinking a lot about how to describe this project in terms of the motivation to create it, how we imagine it being consumed. I've been thinking of some questions for you.

1. ) What was the reason for creating this library? What need did you see?
2. ) Is there a philosophy around FeatherHttp in that you imagine a certain type of developer will find it interesting - who is that person?

I'm enthusiastic about this library because I see it as a fun entry point for new people. What do you think?

[keyse]

Great work but Honestly, as David said, I would also love to hear more about the ‘why’ the framework is needed specially since .NET Core was designed to be low ceremony to begin with.

[davidfowl]

The reason I made this library was to experiment with a more imperative pattern that removed some of the ceremony around Program.cs and Startup.cs. How fast can we put you in a place where you’re writing relevant code (middleware, routing etc). A big part of that was removing callbacks and exposing things as properties. The other things like looking at the amount of concepts exposed host, host builder, sever, application to understand how overwhelming that is compared to other stacks (express, go, django etc)

[rishavs]

Few thoughts;

1. Please do consider and treat F# as a first order citizen in this library, and have snippets for this language as well
2. A lot of feather users might come from outside the .net ecosystem (like nodejs-express, golang net/http users, as they would likely be the ones searching for a get-out-of-my-way-and-let-me-do-stuff kind of micro framework), so it would be great if no assumption of pre-knowledge of the dotnet core ecosystem is considered.
3. Have a dedicated section on authn (basic, jwt, oauth, etc) and authz. A lot of new server devs (personal experience) find that part extremely difficult and a lot of tutorials have a tendency to skip/gloss over that part
4. Section on Deployment (docker, binary),
5. Section on using html templates (even if we use cshtml files, having a dedicated section on this will be super helpful)

IMO, what is needed here is a docs repo, preferably featherhttp/docs
All the docs need to be in markdown and should be generated using current library references. This, I feel, is the best starting point.

In the beginning we can simply link to the docs in that repo from the main repo readme.

A HTTP site can be built on top of this which uses the same md files but converts it to html and hosts it. something like gitbook/jekyll can be used to run this docs toolchain.
We can do that in GH Pages itself or if we want to show the framework in action, maybe we should use the framework itself to run the site.

This is how some of my favorite languages handle documentation. ref: https://github.com/crystal-lang/crystal-book

I would not recommend starting directly on the site, as it would limit community contribution to the docs.

[lohithgn]

@davidfowl just checking - what help do you need to get the docs site up for this?