Update correct instruction to start proxy

[rabwill]

To start the proxy for the first time, see here, it is instructed to Open up a terminal session and change to the samples directory. This step is unnecessary.

[rabwill]

Also adding another readme issue here so I don't spam this repo ;)

The env.js file is already created and my app id is updated when I choose to run the setup.ps1, yet the readme only says about the manual creation of env.js file. I think this should be mentioned as well. https://github.com/microsoftgraph/msgraph-developer-proxy/blob/main/samples/readme.md

[waldekmastykarz]

To start the proxy for the first time, see here, it is instructed to Open up a terminal session and change to the samples directory. This step is unnecessary.

As we're saying in the first paragraph, the tutorial is about running the proxy against the sample app, which is why we ask you to change the working folder.

Could it be that the title is not clear and gives you the impression that it's a generic first time run, rather than first time run with the sample app?

The env.js file is already created and my app id is updated when I choose to run the setup.ps1, yet the readme only says about the manual creation of env.js file.

Manual is an alternative option to PowerShell rather than a follow-up. We should make that clearer. Thank you for bringing it up.

[garrytrinder]

Thank you for reporting this @rabwill apologies for the trouble.

I'll take a look.

[garrytrinder]

As @waldekmastykarz has pointed out, the tutorial is meant to be followed in order, but we can certainly make this clearer.

When be asked to change to the samples directory, it is assumed that you have cloned the repo to your local machine, when instructed in the previous section.

Could it be that the title is not clear and gives you the impression that it's a generic first time run, rather than first time run with the sample app?

Thinking about alternative titles, would any of the following work better:

1. "Testing Microsoft Graph Developer Proxy with a Sample App: A Beginner's Guide"
2. "Intro to Microsoft Graph Developer Proxy Testing: A Hands-On Tutorial"
3. "Microsoft Graph Developer Proxy Testing 101: A Comprehensive Introduction"
4. "The Basics of Testing Microsoft Graph Developer Proxy with a Sample App: A Step-by-Step Guide"
5. "An Introduction to Testing Microsoft Graph Developer Proxy with a Sample App: Tips and Tricks for Beginners"

To improve the flow we could:

• Add a numbered list of the titles in the tutorial to the opening paragraph, this sets the expectations for the reader and reinforces the steps to take
• Remove the emojis from the titles and replace with numbers to again reinforce the steps

[garrytrinder]

The env.js file is already created and my app id is updated when I choose to run the setup.ps1, yet the readme only says about the manual creation of env.js file. I think this should be mentioned as well. main/samples/readme.md

I've raised a PR to add a remark to inform the reader that the script will create the env.js file.

https://github.com/microsoftgraph/msgraph-developer-proxy/pull/108

Does this resolve the confusion @rabwill ? Feel free to comment on the PR.

[garrytrinder]

My preference is title number 4 btw 😊

The Basics of Testing Microsoft Graph Developer Proxy with a Sample App: A Step-by-Step Guide

[waldekmastykarz]

How about "Getting started guide: test a sample app with the Graph Developer Proxy"?

[garrytrinder]

As the page we are suggesting to rename is a sub-page of the Get started page, I don't think we need to repeat that in the title, I think we can drop Getting started guide: but I like the rest of your suggestion.

Test a sample app with Microsoft Graph Developer Proxy is clear what it is and sets the expectations correctly.

[garrytrinder]

@rabwill I've updated the tutorial to reflect the comments made in this issue.

Your feedback is most welcome 👍

[waldekmastykarz]

As the page we are suggesting to rename is a sub-page of the Get started page, I don't think we need to repeat that in the title, I think we can drop Getting started guide: but I like the rest of your suggestion.

Is that obvious though, when you land on the page from an external link? I suspect that you'd focus on the title of the page first and could possibly miss the ToC on the side altogether, losing some of the context inferred from the page structure.

[rabwill]

Thanks folks for clarifying. was confused with the title thinking I had to start the proxy like ngrok. It now makes sense that it is started against a sample. I like @waldekmastykarz 's suggestion Getting started guide: test a sample app with the Graph Developer Proxy as well as the 4th one suggested by @garrytrinder :) Sorry I am not helping.

Alternatively I can also help suggest one Yeeh :D Testing sample applications with Microsoft Graph Developer Proxy: A Beginner's Guide

[garrytrinder]

Is that obvious though, when you land on the page from an external link? I suspect that you'd focus on the title of the page first and could possibly miss the ToC on the side altogether, losing some of the context inferred from the page structure.

If you land on the page from an external link, as you've mentioned you have context from the sidebar as the page is under the Get started section. Ideally we would have a breadcrumb which would give better context, but the GH wiki does not support this, so appreciate that this is not ideal.

However, if that context is missed, the opening paragraph states that This is a step-by-step introduction intended for beginners. and has an additional remark that if you have not installed or configured the proxy then they should do that with a link to the Installation page which will take them back to the first section in the Get started tutorial, when when they complete, the final section links them to this page.

This page is not intended to be the entry point, but we do have sign posts to get folks to the correct place if they do enter here.

Adding Get started to the title of the page makes these section unnecessarily long IMO.

[garrytrinder]

Closing this as I have made updates to the wiki based on the feedback given.

Thanks again for reporting this @rabwill this has really helped us improve our docs 👍