search

featherhttp / framework

A lightweight low ceremony API for web services.
MIT License
810 stars 38 forks source link

Add docs site #7

Open davidfowl opened 4 years ago

davidfowl commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

davidfowl commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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

davidfowl commented 4 years ago

@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 commented 4 years ago

Yes.

I think we should split the content into three categories:

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

dodyg commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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:

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 commented 4 years ago

OK let's start with the absolute beginners.

We will need to write "Getting Started" tutorial:

Then introduce them to the basics:

Data:

How to pair it with JavaScript frameworks

Application Framework:

dodyg commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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

davidfowl commented 4 years ago

I was thinking gh pages as well.

RobotOptimist commented 4 years ago

No problem, I'll switch it to GH Pages

RobotOptimist commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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

RobotOptimist commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 3 years ago

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 commented 3 years ago

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