Identityserver4: Can we make documentation apply the "Keep It Stupid Simple" principle?

[kevingates]

Question / Steps to reproduce the problem

Code examples on documentation page are ambiguous for beginners.

For example, compare this page:

1. https://identityserver4.readthedocs.io/en/latest/quickstarts/1_client_credentials.html
   to this page:
2. https://identityserver4.readthedocs.io/en/latest/quickstarts/2_resource_owner_passwords.html

You will notice the second one (passwords) has example code, but doesn't say where to put the sample code. In short, it presumes a lot. Other pages do this as well.

Suggestions for Improvement

As one who had worked as a manager of customer support and led documentation efforts, I strongly encourage (and honestly , would greatly benefit from) an effort to update all coding examples to explicitly state where the code is to be applied each time. (PS: I know this can't happen everywhere immediately.)

Sometimes this could be added as follows:

---

Add the code below to src > api > Controllers > IdentityController.cs

// Some code

On your next step, you will need to edit the Startup file. Go to : src > app > Startup.cs. Then go under the ConfigureServices method and add:
// Your other code

In short, for people like me, new to backend work, especially in dotnet, it would be helpful if all documentation includes every step and presumes nothing.

The benefit of this is two-fold:

1. It allows newcomers to learn quickly, and therefore also able to become users of IdentityServer, and possibly contributors one day.
2. It helps the current contributors to consistently work through every step, and possible help proactively "debug" and provide support. If they can't think of a simple way to convey something, then likely they need assistance -- which is fine. A solution will be made eventually that is better for everyone.

[redplane]

Same issue.
The tutorial is very hard to beginners. Especially authorization_code, for now, I'm struggling with some issues that have been logged to this repo.

[leastprivilege]

I would very much appreciate if someone would spend the time to make the docs better. But we are both very busy with "real" work right now.

If you - or @LindaLawton - want to take a stab at it, that would be cool.

The "reference" code can be found here:
https://github.com/IdentityServer/IdentityServer4.Samples/tree/master/Quickstarts

[LindaLawton]

I am happy to shine up some of the tutorials.

@leastprivilege do you know if the samples are running the most recent version of .net core? and Ids? do they need upgrading?

[LindaLawton]

note:: The protocol used in this Template is http and the port is set to 5000 when running on Kestrel or a random one on IISExpress. You can change that in the Properties\launchSettings.json file. However, all of the quickstart instructions will assume you use the default port on Kestrel as well as the http protocol, which is sufficient for local development.

Do we still want to use HTTP instead of setting this up to run HTTPS from the start?

[kevingates]

@LindaLawton I appreciate the work you're doing to help people like me to start understanding and hopefully using Identity Server.

Also, I vote if possible for all guides to use HTTPS since that is likely the setup for every user of IS unless there are significant / material reasons to stick with HTTP only.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[kevingates]

Any updates on this?

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.
Questions are community supported only and the authors/maintainers may or may not have time to reply. If you or your company would like commercial support, please see here for more information.

[kevingates]

Any updates on this?

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.
Questions are community supported only and the authors/maintainers may or may not have time to reply. If you or your company would like commercial support, please see here for more information.

[lock[bot]]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.