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?