Mandy/updated device sdk guide #886
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
I'm working out permissions to push the agent code to this repo. The code resides in this repo now but is missing |
There was a problem hiding this comment.
Hey! A few small thoughts throughout and a bigger question for us to hash on with @stmcallister.
I think we should just move forward with your new repo (it does indeed have a better name) and we can archive or delete the old one whenever you're ready.
docs/guides/device-gateway/sdk.md
Outdated
| This guide provides step-by-step instructions for using ngrok as a device gateway. | ||
| This example shows you how to embed connectivity into an application using ngrok's Python SDK to access | ||
| an API running on an IoT device. All the Python code in this example is available in | ||
| [this repo](https://github.com/ngrok-samples/ngrok-python-iot-agent). |
There was a problem hiding this comment.
| [this repo](https://github.com/ngrok-samples/ngrok-python-iot-agent). | |
| [the `ngrok-samples/ngrok-python-iot-agent` repo](https://github.com/ngrok-samples/ngrok-python-iot-agent). |
I like being a bit more explicit with the link target, but take it or leave it!
There was a problem hiding this comment.
Somewhere along my journey, when submitting a PR for some docs, I was taught the same thing. I like the verbose link titles.
There was a problem hiding this comment.
Thank you! This is very helpful feedback. I didn't consider that.
docs/guides/device-gateway/sdk.md
Outdated
|
|
||
| Next, add two `CNAME` records to your DNS provider's registry, providing values from the previous response. | ||
|
|
||
| First add a CNAME record for the wildcard subdomain you just created. |
There was a problem hiding this comment.
| First add a CNAME record for the wildcard subdomain you just created. | |
| Add a CNAME record for the wildcard subdomain you just created. |
docs/guides/device-gateway/sdk.md
Outdated
|
|
||
| ## Create a bot user | ||
|
|
||
| First, you’ll create a bot user so that in the next section, you can create an agent authtoken independent of any user account. |
There was a problem hiding this comment.
| First, you’ll create a bot user so that in the next section, you can create an agent authtoken independent of any user account. | |
| Create a bot user so that in the next section, you can create an agent authtoken independent of any user account. |
| with the value you set on line `109` of the code and `{URL_PART}` with the value of the | ||
| `url_part` property of the list tunnels request: | ||
|
|
||
| ```curl |
| on `device342.sitea.{YOUR_DOMAIN}` and `device896.sitea.{YOUR_DOMAIN}` without having to reserve them individually. | ||
| It can be helpful to create a separate subdomain for each site you wish to connect to. | ||
|
|
||
| Run the following command, substituting your API key for `{API_KEY}` and your domain for `{YOUR_DOMAIN}`: |
There was a problem hiding this comment.
@DevMandy @stmcallister (and honestly everyone else who writes docs...)
We should come up with a standard way of defining these "variables" in code blocks that users need to find and replace. I don't have a strong opinion about which one, but I think if we're consistent internally then they'll more easily be able to pick them out of complex code/config.
Any thoughts?
There was a problem hiding this comment.
Completely agree! I ❤️ consistency! I would vote to find out if we already use a particular standard more often and stick to that one. I don't have strong feelings about which style of syntax we use just that it's consistent.
There was a problem hiding this comment.
At the moment, these are consistent across guides (or at least new guides). I can look at making them consistent as part of the guides reboot project. I agree they should be consistent.
There was a problem hiding this comment.
I was using <API_KEY> in previous guides, but I'm happy to follow your path here with the brackets. They do stick out nicely from typical YAML/JSON syntax.
docs/guides/device-gateway/sdk.md
Outdated
| This guide provides step-by-step instructions for using ngrok as a device gateway. | ||
| This example shows you how to embed connectivity into an application using ngrok's Python SDK to access | ||
| an API running on an IoT device. All the Python code in this example is available in | ||
| [this repo](https://github.com/ngrok-samples/ngrok-python-iot-agent). |
There was a problem hiding this comment.
Somewhere along my journey, when submitting a PR for some docs, I was taught the same thing. I like the verbose link titles.
docs/guides/device-gateway/sdk.md
Outdated
| https://api.ngrok.com/bot_users | ||
| ``` | ||
|
|
||
| You should receive a 201 response similar to the following: |
There was a problem hiding this comment.
| You should receive a 201 response similar to the following: | |
| You should receive a `201` response similar to the following: |
There was a problem hiding this comment.
NO ONE catches stuff like this! I made that mistake in the last 5 guides and no one caught it. Thank you! :)
| } | ||
| } | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Is it me, or did that indentation get crazy?
There was a problem hiding this comment.
No, it was wonky! Thank you!
Change formatting Co-authored-by: Joel Hans <[email protected]>
This is a new PR that replaces this one. I pulled out the changes in scope and will handle the additional requests around marking steps as optional in a separate PR.