DOCS-3613: Iterate on Connect Devices #4037
Conversation
viambot
added
the
safe to build
✅ Deploy Preview for viam-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
|
||
| Viam supports a wide variety of sensors, cameras, and other physical hardware, with APIs for each of the following types of hardware: | ||
|
|
||
| {{< cards >}} |
There was a problem hiding this comment.
Not sure where else to put this comment but - given that this is now here, I think we could remove the links to the component API's that appear under "Configure supported hardware"?
There was a problem hiding this comment.
We might need to figure out a new place to put them then, because people keep saying they're buried. :/
There was a problem hiding this comment.
Let's leave them in for now, and discuss with Naomi and Ian.
Jotting down the options I see at the moment:
- Further integrate them with "Configure supported hardware" by adding component filters to the "omni search" box, or splitting up that search box by component. This goes against the idea of directing people to the Registry page in app, which I think is better.
- Have a reference-style page "Component API's" in the left nav
There was a problem hiding this comment.
yeah I guess this is one we can talk about between naomi and jessamy and I. definitely a lot of different opinions here so i don't think we'll come to something async.
There was a problem hiding this comment.
I don't mind adding a forwarding link to the reference section that goes to the Component APIs page. I don't think it's sufficient. I do think the first point Esha makes is important. If I as a user come to this page wondering "does viam support my arm" it takes quite a bit of text to wade through to get any hint that arms are supported and how to figure out whether my arm is supported. I think something that makes it easily scannable to see "arms are supported" would be great. Happy to discuss synchronously.
There was a problem hiding this comment.
Let me know if you'd like me to join for this synchronous discussion :) I would probably lean towards adding a "Browse Component API's" reference-style page so that the left nav is:
- Learn the basics
- Set up a computer or SBC
- Set up an ESP32
- Browse Component API's
- Configure supported hardware
- Integrate other hardware
- Test your machine
"Browse Component API's" would have basically the current Component pages (like this), except with the API methods moved above the supported models.
And I'd probably suggest removing the "omni search" box of models from "Configure supported hardware" in favor of linking to the Registry page in app.
I like this because it fits browsing component API's into what feels like an appropriate place in the user flow, while also making it easily find-able as a reference page.
I'm mainly not sure how to square this with the Component API's also existing in the Dev Tools reference.
One related thought is Eliot said he would be fine with moving "Integrate other hardware" out of this section since it's pretty heavyweight.
I know this touches on a lot of aspects, just wanted to get my thoughts down somewhere! If you all want to just keep this in mind for your discussion, that's fine too.
There was a problem hiding this comment.
Can you tell me what you expect users to be looking for then? What questions do you imagine they have at that point that would be answered by that page?
I think that description would mean that "Browse Component APIs" would not be action orientd. The main goal would be to show/educate the user about Component APIs and I think that should happen while they complete tasks, not separately. Am I seeing that wrong?
Do you two have ideas for what to do with Integrate other hardware if it's not in this section?
There was a problem hiding this comment.
Hmm. The tough thing is for some of this more reference content, there are a few different tasks where it's relevant. For example for the Component API's:
Initially browsing -> "What types of hardware does Viam support? What kinds of API's are there?"
Designing/implementing their machine/solution -> "What were the specific API methods can I call, again?"
Writing a module -> "What API methods do I need to implement?"
It seems reasonable to embed the content in an "early" task a user would do (and Connect Devices is sort of a combination of the first two), and I was thinking we could name it in a way that makes it easy to find for other tasks.
For "Integrate other hardware", it does fit under Build & Integrate. Perhaps it could be its own section at the same level as "Connect Devices" and "Build apps"?
If it's easier to discuss in person, happy to meet this week or at the backstop meeting Jessamy created!
| 1. [Data capture and sync](/data-ai/capture-data/capture-sync/) is supported for microcontrollers. | ||
| You can click the **Add method** button on any component's config card to configure data capture for that component. |
There was a problem hiding this comment.
| 1. [Data capture and sync](/data-ai/capture-data/capture-sync/) is supported for microcontrollers. | |
| You can click the **Add method** button on any component's config card to configure data capture for that component. |
There was a problem hiding this comment.
Is this inaccurate? I was thinking that since it's the one service that is supported for the Micro-RDK maybe it should be talked about here since they might otherwise assume they can't do it.
There was a problem hiding this comment.
It's not inaccurate, but related to my comment below about "Configure supported hardware" applying to MicroRDK too, I just think it makes more sense to have this page be just about setting up MicroRDK/viam-micro-server
| A secure connection is automatically established between your machine and the Viam app. | ||
| When you update your machine's configuration, `viam-micro-server` automatically gets the updates. | ||
|
|
||
| 1. Use the **+** button on your machine's **CONFIGURE** tab to add any of the supported components listed above. |
There was a problem hiding this comment.
| 1. Use the **+** button on your machine's **CONFIGURE** tab to add any of the supported components listed above. |
This is the same content as in "Configure supported hardware", and I think it's better for the user to follow the same left nav flow for both, since "Test your machine" also works the same way for both.
(Note that right now MicroRDK modules all have to be configured via raw json, but that will probably change soon, and I think it's fine for the docs to gloss over that for now.)
In a future iteration of "Connect Devices" (maybe even soon after this one), we could consider splitting up the MicroRDK "Build custom firmware" and "Write your own module" docs so that the "Build custom firmware" portion is on this page. But even then, after the user builds their firmware, they would resume the regular left nav flow for adding modules to their config and testing their machine.
There was a problem hiding this comment.
Hmm I guess I was thinking Micro users wouldn't necessarily go to Configure supported hardware since it's more rdk-centric now.
Wait RE raw JSON, so is https://docs.viam.com/operate/reference/components/servo/gpio-micro-rdk/ totally wrong?
There was a problem hiding this comment.
I believe any pages that say to use the dropdown for a MicroRDK model are wrong - I had asked about this a couple months ago and can't remember if I got a clear answer in person (https://viaminc.slack.com/archives/C0644TMU36U/p1735937348630189). Asking again on Slack
Hmm, I guess I don't see Configure supported hardware as rdk-centric:
- "Configure hardware on your machine" will eventually apply to MicroRDK models, once they're in the app.viam dropdown and don't require being added via raw json. (Even now, conceptually it applies to MicroRDK models, we just haven't described the raw json method there)
- "Browse supported hardware" will apply to MicroRDK models, once they're in the Registry page on app (groundwork is being laid for this in the cloud builds project)
- "Virtual hardware components" conceptually applies, even if we don't have any virtual MicroRDK models atm
- "Add software services to your machine" applies, even if MicroRDK currently only supports the data capture service
Happy to chat about this over Zoom too - I'm pretty free this afternoon!
|
|
||
| 1. [Test your machine](/operate/get-started/test/) by using the **TEST** panel of each configured component's config card to, for example, view your camera's stream or turn your motor. | ||
|
|
||
| 1. From there, you have many options including: |
There was a problem hiding this comment.
Similarly not sure where to put this, but I think we should remove the "Configure machine settings" and "Reuse device configuration" left nav links. It feels odd to have some next steps here and some in the left nav, and for them to be different. We could optionally fold those links into the next steps section here
There was a problem hiding this comment.
Okay fair point. Naomi may have thoughts since they're to her section and it won't change the main flow here besides the oddness you duly point out.
There was a problem hiding this comment.
Sounds good - happy to leave in until Naomi returns
There was a problem hiding this comment.
@npentrel are you okay with these two being removed from left nav? There are lots of possible paths after the basic steps (as mentioned offline yesterday) so I think it makes sense to remove these links and instead present options as next steps at bottom of configure supported hardware
There was a problem hiding this comment.
I worry they won't be discoverable but let's leave them off for now.
| @@ -0,0 +1,98 @@ | |||
| --- | |||
There was a problem hiding this comment.
hey as we chatted about last week - i just want to confirm this is intended to be helpful but not required to get started? under the assumption that a lot of people very well might skip this page. Also, i know this might not matter a huge amount, but I think i like renaming this to something without a verb since it is not procedural content. since github uses 'about github and git' maybe 'About Viam'? 'Overview'? etc.
There was a problem hiding this comment.
I actually kind of like the verb - feel like it encourages people to start here :P
There was a problem hiding this comment.
Oh I'd thought you wanted verbs across the board, so we came up with this and I somewhat agree with Esha though don't feel strongly. We used to have a page called "About Viam" and some people thought it meant "About Viam as a company" instead of "About the Viam platform." I do think Overview would be okay, and people would be less likely to read it.
If we want most people to skip over this page, then we can make it Overview, but then we need to move "What is a machine?" to each of the setup pages because we've gotten overwhelming feedback that that's a key helpful section.
There was a problem hiding this comment.
Discussed w/Esha offline and we feel that "Learn the basics" is best here. Yes people can skip over it but with this title, they're more likely to come here if they have questions as they move through other content.
There was a problem hiding this comment.
i swear I won't abuse my veto power too much but I do actually feel kind of strongly about keeping verb+object for procedural content and nouns/adjectives/etc (e.g. "About The Viam Platform" or "Viam Overview") for context-setting and/or reference content.
There was a problem hiding this comment.
Okay so I was about to change it to overview but then remembered we already have a link called "Overview" in the left nav. I think having both "Overview" and even "About the Viam platform" is going to be really confusing. I think for AI and Data it'd make sense to call it "AI & Data Overview" for example, but for Build & Integrate it gets hairy because this section is the jumping off point for using Viam as a whole. I see three options in my order of preference:
- Leave it all as-is.
- Get rid of the "Overview" thing in the left nav for all areas, since you can also get there by clicking the area name anyway, and it doesn't provide that much info. Change this basics page title to "Overview" or "Viam overview".
- Change all the "Overview" titles across the docs to be more specific to their areas. For Build and Integrate, that means call it "Build & Integrate Overview" I guess. Change this page to "About the Viam platform."
There was a problem hiding this comment.
1 is off the table. Unless this page covers something task based (i.e. unless you make content changes), the page should have a different link title. I don't think "Overview" communicates what that page entails. The page's title is already Viam basics. You could go with that or something like Ian suggested. I'd throw "About Viam and machines" into the mix.
There was a problem hiding this comment.
For thread coherency: Ian said via email reply (see conversation page on this PR) fine to leave as-is.
Okay I will change to Viam basics in left nav.
|
|
||
| {{< expand "Supported systems" >}} | ||
| ## Prerequisite: Make sure you have a supported operating system |
There was a problem hiding this comment.
instead of this text, can we use code to make it super clear immediately:
linux:
arch=$(uname -m); bits=$(getconf LONG_BIT); [[ ("$arch" == "x86_64" || "$arch" == "aarch64") && "$bits" == "64" ]] && echo "✅ Your system can run viam-server" || echo "❌ Your system cannot run viam-server"macos
[[ "$(uname -s)" == "Darwin" && ("$(uname -m)" == "x86_64" || "$(uname -m)" == "arm64") ]] && echo "✅ Your system can run viam-server" || echo "❌ Your system cannot run viam-server"windows
(Get-WmiObject -Class Win32_OperatingSystem).OSArchitecture -eq "64-bit" -and (wsl --status 2>$null) -ne $null ? "✅ Your system can run viam-server" : "❌ Your system needs WSL for viam-server"
There was a problem hiding this comment.
Interesting. When you say "instead of this text" do you mean this entire section? Replacing this might be intimidating to some users, and for any user, they'd need to have access to their terminal. If someone's looking at the docs on their phone/on the go and/or they're not super technical, this might make it less clear.
I could add each of these lines to the bottom of the relevant expander below--maybe that's what you're suggesting?
There was a problem hiding this comment.
no, definitely not suggesting adding to this section, i'm suggesting trying to simplify or make it more procedural. this feels like a good example of a place where it feels we are overcomplicating things. i know these are not identical since its OS vs OS+arch, but compare these two:
vs
so my thought process is:
we're telling people that they need to run on a certain arch. if they know the arch of their system, they're done here. if they don't then the first thing they need to do is figure out their arch. how do they do that? they google. what does google tell them? run certain commands. so why not just cut straight back to the beginning and give them the commands?
i would assume this whole section could be boiled to something like:
docs/operate/get-started/setup.md
Outdated
|
|
||
| When you create a new machine in the Viam app, Viam generates a unique set of credentials for that machine that connect the physical machine to its instance in the Viam app. | ||
| ## The details |
There was a problem hiding this comment.
are we sure this should be here instead of in the reference?
There was a problem hiding this comment.
Yes. The details here are directly related to the content above, and people don't have to read it, but if they need it they won't find it in reference.
There was a problem hiding this comment.
Can you explain why they won't find this in reference content? It does to me feel like a bit of a dumping ground and the title being so unspecific does also indicate that. I think mainly because the "How the configuration works" feels out of place - we haven't yet configured anything. So should that be with the next page?
Then you'd be left with two pieces of info that are about the insntallation only. Though I am also wonderign if the agent vs manual should be with Step 4 instead or whether it's even needed at all. It may be that we have enough info in App now on this that we don't need this. Thoughts?
There was a problem hiding this comment.
Based on user interviews and other feedback, a few things seem true about reference:
- No one looks in reference, especially because it's collapsed, and because "Reference" sounds scary/like too much
- People are confused by the different reference contents across sections
- People wouldn't know what they were even looking for, especially for how viam-server connects to the app. If someone was curious maybe they'd ask the chatbot but I doubt they'd dig through reference.
Also user feedback has been incredibly positive on the current Start a Machine page which includes all this. Perhaps I should actually pull "What is a machine" back onto this page in case folks don't read the overview.
I do think there's confusion about how all the pieces tie together, and this is one of those pieces, basically answering "What does me setting up my machine in the app actually do and how does that fit in with all the other pieces of Viam, and does my machine have to always be online?" This content is about the connection between the app and the machine which is established through these steps, so it is relevant here.
I don't think there's quite enough information about viam-agent vs manual in the app. I will make this section hidden content though and hope the curious will ask AI.
|
|
||
| Viam supports a wide variety of sensors, cameras, and other physical hardware, with APIs for each of the following types of hardware: | ||
|
|
||
| {{< cards >}} |
There was a problem hiding this comment.
yeah I guess this is one we can talk about between naomi and jessamy and I. definitely a lot of different opinions here so i don't think we'll come to something async.
docs/operate/get-started/test.md
Outdated
| @@ -0,0 +1,30 @@ | |||
| --- | |||
There was a problem hiding this comment.
this feels kinda strange/jammed in as far as 'how tos' go. i feel like people aren't really going to be actively looking to take this step? it feels more like we wanted to point people to this feature and so we jammed that idea into a Test Your Machine section. should this be more about troubleshooting?
i don't know if this should be contained within the 'setup hardware' stuff, but it feels like by the end of setting up hardware you should have (and know you have) working hardware - you shouldn't need to go through another process to actually see that?
There was a problem hiding this comment.
I would be fine with deleting this page and just having one sentence saying you can use the test panel to test your hardware, at the end of configuring it. @EshaMaharishi what do you think?
There was a problem hiding this comment.
I actually think it's nice to have this page - using the test panels to make sure your configuration (hardware and Viam config) is working correctly feels like part of the main flow. I was going to suggest we show a few more test panel examples (in follow-up work that adds more screenshots).
There was a problem hiding this comment.
We do want to have only just enough documentation to get users along the necessary path from A to B, and I don't think this page is critical.
If they've just configured hardware, they're already looking right at the config panel in the app where the test section is, so it seems like tacking on one step there instead of in a separate page makes sense. Then if they test it and it doesn't work, they can fix their configuration--you could consider it all part of one process. In the interest of brevity, and not making users click through as many pages, I do really want to ax this page.
Screenshots might break the flow if inserted into the configure page, since right now it goes to How module config works, and then stuff about configuring more things which isn't related to testing. But I could add using the test panel to the GIF, which is going to become shorter when I update it to use inline module docs.
There was a problem hiding this comment.
I agree that test your machine is nice to have and it flows pretty well this way, but I think we need to be more ruthless in cutting down the overall length of the docs. Edit: And I can't say i've seen many AI questions about how to test components, though there have been some FWIW.
There was a problem hiding this comment.
yeah i'd rather add one step to configure than have a whole page. if you need a whole page to explain how to make sure the thing you just did actually worked, then i think the thing you just did needs to be improved in giving feedback on its success.
alternatively, I do still think it wouldn't be crazy to have some of this under troubleshooting - like you did the configuration but you're actually still not sure if it worked or you think you did something wrong - then how do you proceed?
There was a problem hiding this comment.
So we have the troubleshoot page here....I could link to that and also tell people to ask the chatbot? I feel like it does a decent job with this, and people can have a wide variety of config issues so hard to be inclusive without making the configure page very long
| ## What this guide covers | ||
|
|
There was a problem hiding this comment.
[minor - not merge blocking] But why do you think this is needed/an improvement?
I'm always wary of headlines following headlines without text in between
There was a problem hiding this comment.
Ian has recently been advocating for all content being under headings, so that people know whether or not they need to read the text. GitHub generally does this, aside from their big gray one-short-sentence subtitles at the tops of pages. I don't feel strongly either way but given that direction figured I should start moving connect devices towards that so we can see how it fits/whether we like it.
docs/operate/get-started/setup.md
Outdated
|
|
||
| {{< /expand >}} | ||
|
|
||
| For 32-bit systems, see [Set up an ESP32](/operate/get-started/setup-micro/). |
There was a problem hiding this comment.
[major] If I am a 32bit Linux or Windows user this does not apply to me. We can't use 32-bit and 64-bit to differentiate between viam-micro-server and viam-server. The only case you should go to the Set up an ESP32 page is if you are using an ESP32 microcontroller.
FWIW I believe we currently have a beta for 32-bit ARM - according to the app at least.
There was a problem hiding this comment.
Ah yes I should have said this here:
| For 32-bit systems, see [Set up an ESP32](/operate/get-started/setup-micro/). | |
| For 32-bit microcontrollers, see [Set up an ESP32](/operate/get-started/setup-micro/). |
But also wasn't aware until now of that beta support. I guess we should include it here and just say it's in beta. I guess I'll dig into the state of that for Windows vs Linux.
docs/operate/get-started/setup.md
Outdated
| @@ -75,27 +52,44 @@ If your SBC or other computer already has a supported operating system installed | |||
| {{< /cards >}} | |||
|
|
|||
| {{< /expand >}} | |||
| {{< expand "Linux laptop or desktop" >}} | |||
There was a problem hiding this comment.
The intro text says "the following operating systems" but then proceeds to list sbc and linux laptop or desktop. I think there's some conflation of OS and architecture. Ian is already suggesting changes. If you can make those while making this a bit less confusing that would be great.
|
|
||
| Viam supports a wide variety of sensors, cameras, and other physical hardware, with APIs for each of the following types of hardware: | ||
|
|
||
| {{< cards >}} |
There was a problem hiding this comment.
I don't mind adding a forwarding link to the reference section that goes to the Component APIs page. I don't think it's sufficient. I do think the first point Esha makes is important. If I as a user come to this page wondering "does viam support my arm" it takes quite a bit of text to wade through to get any hint that arms are supported and how to figure out whether my arm is supported. I think something that makes it easily scannable to see "arms are supported" would be great. Happy to discuss synchronously.
docs/operate/get-started/test.md
Outdated
| @@ -0,0 +1,30 @@ | |||
| --- | |||
There was a problem hiding this comment.
yeah i'd rather add one step to configure than have a whole page. if you need a whole page to explain how to make sure the thing you just did actually worked, then i think the thing you just did needs to be improved in giving feedback on its success.
alternatively, I do still think it wouldn't be crazy to have some of this under troubleshooting - like you did the configuration but you're actually still not sure if it worked or you think you did something wrong - then how do you proceed?
|
|
||
| {{< expand "Supported systems" >}} | ||
| ## Prerequisite: Make sure you have a supported operating system |
There was a problem hiding this comment.
no, definitely not suggesting adding to this section, i'm suggesting trying to simplify or make it more procedural. this feels like a good example of a place where it feels we are overcomplicating things. i know these are not identical since its OS vs OS+arch, but compare these two:
vs
so my thought process is:
we're telling people that they need to run on a certain arch. if they know the arch of their system, they're done here. if they don't then the first thing they need to do is figure out their arch. how do they do that? they google. what does google tell them? run certain commands. so why not just cut straight back to the beginning and give them the commands?
i would assume this whole section could be boiled to something like:
| @@ -0,0 +1,98 @@ | |||
| --- | |||
There was a problem hiding this comment.
i swear I won't abuse my veto power too much but I do actually feel kind of strongly about keeping verb+object for procedural content and nouns/adjectives/etc (e.g. "About The Viam Platform" or "Viam Overview") for context-setting and/or reference content.
|
fine leave as is
…On Fri, Mar 7, 2025 at 7:40 PM Jessamy Taylor ***@***.***> wrote:
***@***.**** commented on this pull request.
------------------------------
In docs/operate/get-started/basics.md
<#4037 (comment)>:
> @@ -0,0 +1,98 @@
+---
Okay so I was about to change it to overview but then remembered we
already have a link called "Overview" in the left nav. I think having both
"Overview" and even "About the Viam platform" is going to be really
confusing. I think for AI and Data it'd make sense to call it "AI & Data
Overview" for example, but for Build & Integrate it gets hairy because this
section is the jumping off point for using Viam as a whole. I see three
options in my order of preference:
1. Leave it all as-is.
2. Get rid of the "Overview" thing in the left nav for all areas,
since you can also get there by clicking the area name anyway, and it
doesn't provide that much info. Change this basics page title to "Overview"
or "Viam overview".
3. Change all the "Overview" titles across the docs to be more
specific to their areas. For Build and Integrate, that means call it "Build
& Integrate Overview" I guess. Change this page to "About the Viam
platform."
—
Reply to this email directly, view it on GitHub
<#4037 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AADV5ER3MG6JH42KKSNXWDL2TI36DAVCNFSM6AAAAABX665MO2VHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDMNRYGY4DQNZXGI>
.
You are receiving this because you commented.Message ID:
***@***.***>
--
Ian M. Whalen / 347-563-8342
http://www.ianwhalen.com
http://www.linkedin.com/in/ianwhalen
|
| @@ -0,0 +1,98 @@ | |||
| --- | |||
There was a problem hiding this comment.
1 is off the table. Unless this page covers something task based (i.e. unless you make content changes), the page should have a different link title. I don't think "Overview" communicates what that page entails. The page's title is already Viam basics. You could go with that or something like Ian suggested. I'd throw "About Viam and machines" into the mix.
|
|
||
| Viam supports a wide variety of sensors, cameras, and other physical hardware, with APIs for each of the following types of hardware: | ||
|
|
||
| {{< cards >}} |
There was a problem hiding this comment.
Can you tell me what you expect users to be looking for then? What questions do you imagine they have at that point that would be answered by that page?
I think that description would mean that "Browse Component APIs" would not be action orientd. The main goal would be to show/educate the user about Component APIs and I think that should happen while they complete tasks, not separately. Am I seeing that wrong?
Do you two have ideas for what to do with Integrate other hardware if it's not in this section?
|
|
||
| 1. [Test your machine](/operate/get-started/test/) by using the **TEST** panel of each configured component's config card to, for example, view your camera's stream or turn your motor. | ||
|
|
||
| 1. From there, you have many options including: |
There was a problem hiding this comment.
I worry they won't be discoverable but let's leave them off for now.
docs/operate/get-started/setup.md
Outdated
| `viam-server` can run on any computer that runs one of the following operating systems: | ||
|
|
||
| - Linux 64-bit operating systems running on AArch64 (ARM64) or x86-64 architectures | ||
| - macOS | ||
| - Windows |
There was a problem hiding this comment.
This is duplicated info and probably now doesn't need to be. For Linux it provides a bit more info which you can put in the LInux tab instead.
Also please ensure this is correct. I think we'd want to cover the 32-bit ARM version we support as well?
There was a problem hiding this comment.
Ok moved the info. RE 32-bit ARM, I'm talking to Abe about it and he's going to check setup instructions for it next week. I'll track here https://viam.atlassian.net/browse/DOCS-3671
docs/operate/get-started/setup.md
Outdated
|
|
||
| Viam also offers a lightweight binary to support the following 32-bit microcontrollers: | ||
| For 32-bit microcontrollers, see [Set up an ESP32](/operate/get-started/setup-micro/). |
There was a problem hiding this comment.
this should be at the end of the section, not above the command you want them to run
There was a problem hiding this comment.
Yeah with the above coming out I will move it. If that was staying it, i worried people would scan that quickly and think no esp32 support. Removing!
docs/operate/get-started/setup.md
Outdated
|
|
||
| When you create a new machine in the Viam app, Viam generates a unique set of credentials for that machine that connect the physical machine to its instance in the Viam app. | ||
| ## The details |
There was a problem hiding this comment.
Can you explain why they won't find this in reference content? It does to me feel like a bit of a dumping ground and the title being so unspecific does also indicate that. I think mainly because the "How the configuration works" feels out of place - we haven't yet configured anything. So should that be with the next page?
Then you'd be left with two pieces of info that are about the insntallation only. Though I am also wonderign if the agent vs manual should be with Step 4 instead or whether it's even needed at all. It may be that we have enough info in App now on this that we don't need this. Thoughts?
| layout: "docs" | ||
| type: "docs" | ||
| imageAlt: "Configure a Machine" | ||
| images: ["/viam.svg"] | ||
| description: "Use supported hardware with your machine." | ||
| modulescript: true | ||
| no_list: true |
There was a problem hiding this comment.
So this breaks the pattern of making this a linear path through the pages. I think you don't need to do this
| no_list: true |
There was a problem hiding this comment.
I know it's different from other spots but that's just it--this page is a bit different in that it's a jumping off point for many different next steps. Seems odd to have both next steps and a button to make modules.
| Modules for 64-bit architecture run alongside [`viam-server`](/operate/reference/viam-server/) as separate processes, communicating with `viam-server` over UNIX sockets. | ||
| When a module initializes, it registers its {{< glossary_tooltip term_id="model" text="model or models" >}} and associated [APIs](/dev/reference/apis/) with `viam-server`, making the new model available for use. | ||
| `viam-server` manages the [dependencies](/operate/reference/viam-server/#dependency-management), [start-up](/operate/reference/viam-server/#start-up), [reconfiguration](/operate/reference/viam-server/#reconfiguration), [data management](/data-ai/capture-data/capture-sync/), and [shutdown](/operate/reference/viam-server/#shutdown) behavior of your modular resource. | ||
| With your machine configured, you have a number of options: |
There was a problem hiding this comment.
| With your machine configured, you have a number of options: | |
| If you have more custom hardware you need to integrate, continue to [Integrate other hardware](...). | |
| If you have configured all your hardware you can start a number of projects: |
There was a problem hiding this comment.
This is fine for now but there's more work to be done for this page. I think it's important that a user coming to this page to configure an arm get's feedback fairly quickly that arms are supported and a way to figure out which arms are supported.
There was a problem hiding this comment.
So, I believe this is what @EshaMaharishi and I advocated for previously but Ian's feedback was that this should be a more action-oriented, configuration-forward page. I've created a meeting for us all to discuss this and how to surface APIs synchronously.
There was a problem hiding this comment.
I don't think this is necessarily conflicting. I think one of Esha's suggestions was to make possibly to search resources by subtype, which would also fulfill the goal of providing a strong visual cue that "yes arms are supported and you are in the right place"
Co-authored-by: Esha Maharishi <esha.maharishi@gmail.com>
Co-authored-by: Esha Maharishi <esha.maharishi@gmail.com>
Co-authored-by: Esha Maharishi <esha.maharishi@gmail.com>
… place of services
|
🔎💬 Inkeep AI search and chat service is syncing content for source 'Viam Docs (https://docs.viam.com)' |
Once all else is agreed upon, remaining cleanup before merging:GIF to be updated for inline module docsBroken links to be fixedBoards carousel shouldn't link anywhere; just want images (if we want to keep it there). Setup links are still provided in the prerequisite OS expander anyway, and we don't want people jumping off the concepts page.