DOCS-3906, DOCS-4008: Change module IA, surface popular reference #4356
Conversation
✅ Deploy Preview for viam-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
viambot
added
the
safe to build
| If any modules are still running after 90 seconds, `viam-server` kills them as well. | ||
| This means that if four modules are running and the first three each fail to shut down within 30 seconds each, the fourth is killed immediately at the 90 second mark. | ||
|
|
||
| For microcontrollers, you must flash a [firmware build that includes the Micro-RDK](/operate/get-started/other-hardware/micro-module/) and one or more modules onto your device. |
There was a problem hiding this comment.
this is peculiar on this page. Nothing else here even mentions the Micro-RDK
There was a problem hiding this comment.
This is preexisting content; Esha and I previously figured it's important to point out that micro modules are different from the modules discussed on this page
There was a problem hiding this comment.
Do you think this helps?
| For microcontrollers, you must flash a [firmware build that includes the Micro-RDK](/operate/get-started/other-hardware/micro-module/) and one or more modules onto your device. | |
| Microcontroller modules function differently; you must flash a [firmware build that includes the Micro-RDK](/operate/get-started/other-hardware/micro-module/) and one or more modules onto your device. |
There was a problem hiding this comment.
it's a step in the right direction but explaining how to flash it on the device doesn't seem equivalent to lifecycle information. Are they started in a specific order? Are there dependencies? probably not worth investigating
Microcontroller modules fuction differently and are embedded in the firmware for your device.
For more information see [Modules for ESP32](/operate/get-started/other-hardware/micro-module/).
| @@ -0,0 +1,1102 @@ | |||
| --- | |||
| title: "Create a module" | |||
There was a problem hiding this comment.
for esp32 this is called Modules for ESP32, so should this not just be modules? And then possibly have hello world, dependencies, meta.json, update and manage and lifecycle under it?
There was a problem hiding this comment.
- If it's just called "modules," that doesn't tell people whether it's reference content or how-to. I'd say "Integrate other modules" is already approximately equivalent to "Modules," just in imperative per agreed upon top-level nav standards.
- If it continues to be called "Create modules" (my preference), then Update and manage doesn't belong inside it since that's post-creation
- The Modules for ESP32 page could be called "Create a module for ESP32", it's just that that's long. It could go within "Create modules" I guess
There was a problem hiding this comment.
Hmm yeah I think it could go in create modules OR maybe it could be a subpage of "set up an esp32"? It doesn't actually feel like it belongs with "regular" modules other than by virtue of also being called modules. They don't work the same. The module configuration, lifecycle, updating and managing modules, nothing here applies to the esp32 modules. And if you encounter the module for esp32 here you have already flashed your hardware because it's after "set up an esp32" so you'd have to go back and redo that. I mean you probably will have to anyway while developing but it still feels odd. So yeah either move under create or under setup I think
There was a problem hiding this comment.
Hmmm was about to move micro modules under setup esp32 but it occurs to me: If someone sees "Integrate other modules" they might look there for esp32 modules, and not see anything, and take a while to find this page, because they won't look in "setup" if they've already set it up. So actually, the very fact that nothing else in the Integrate Other Modules section has nothing to do with ESP32 is a reason to put it there so people see it instead of looking at the other things.
Also though, maybe it doesn't matter that much since people will use search and ask AI, and it's better to err on the side of not moving the micro modules page at all so there's one less redirect.
I think it makes sense to just move it to the bottom of the list so it's not smack in the middle of the flow, but keep it in the folder it's currently in.
There was a problem hiding this comment.
I'd suggest putting a callout on the create a module page? "If you're using ESP32, see ..."
I think the risk is that people will assume that all the other pages work with micro-RDK and actually none of them are relevant to Micro-RDK modules. Your call I'll approve it for now
There was a problem hiding this comment.
Yeah I share your concern to an extent but I'm hoping that leaving it called "Modules for ESP32" instead of "Create modules for ESP32" will in a small way mitigate that--I'm hoping people will read it as "Everything to do with modules for ESP32." And I'm hoping that just seeing "ESP32" not buried another layer deeper will cause them to click it. Going to leave for now.
There was a problem hiding this comment.
(Meaning I'll leave the page where it is, but I think a callout wouldn't hurt so I'll add that)
| @@ -0,0 +1,1102 @@ | |||
| --- | |||
| title: "Create a module" | |||
There was a problem hiding this comment.
also previous page should have a next button linking to this, meta.json should have next link to update and manage and please check for any other dangling ends. The idea is that this is a path through the docs you can click.
There was a problem hiding this comment.
For meta.json I should actually remove previous and not have any forward/back buttons right, since it's just a reference page and not part of flow per se
For linking to create a module, should it?? We have a variety of possible next steps listed on the previous page, not just this one.
There was a problem hiding this comment.
I get that it doesn't feel like a next step but wouldn't be too strict about that. If we interleave the reference pages then they become part of the flow.
So I think meta.json should continue to update and manage modules and I think module configuration can continue to lifecycle of a module.
| title: "Integrate other resources with modules" | ||
| linkTitle: "Integrate other modules" |
There was a problem hiding this comment.
| title: "Integrate other resources with modules" | |
| linkTitle: "Integrate other modules" | |
| title: "Develop modules" | |
| linkTitle: "Develop modules" |
While I understand the general thoughts behind 'integrate other modules' (we have talked about this at length, after all), I fear that 'integrate' is overused and rendered just as meaningless a term as 'leverage' and 'utilize' and their ilk. And I'm honestly not sure what 'other' accomplishes in this case.
So how about something completely different? While I would be fine with the simple title 'Modules', I'm inclined to agree that we should stick with verb phrases here. When I look at all of these new titles, especially the new 'lifecycle' one, it reminds me of SDLC... so how about 'develop' as a verb phrase? Should be very easy for users to find if they're looking for information about writing and publishing modules, I think.
There was a problem hiding this comment.
The idea is that "Integrate other modules" is in contrast to "Configure supported hardware." Like, you check whether it's already supported by an existing module, and if not, you integrate your thing with a new module. Which indeed, you do "develop,"... but the point of development is to integrate, so "integrate" focuses on the ultimate goal more (theoretically).
There was a problem hiding this comment.
Ultimately, the term 'integrate' is just a bit too abstract for me in this context. 'Develop' feels more grounded in the realities of, well, devloping software. And while I now understand that 'other' is meant to contrast with 'supported', I think that subtlety is lost when I'm scanning the sidebar.
Not a big deal, so if you're happy with the existing title, stick with it. I think introducing the word 'modules' into this section title is the most important part anyway.
There was a problem hiding this comment.
Yeah I don't disagree that "integrate" is a bit more ambiguous, but this gets into the discoverability vs findability goals--gonna leave for now but heard!
|
Since naomi has already approved, no need for me to give a full review. But I just wanted to say that I really love this change, especially the decision to pull the lifecycle and meta.json reference content out into separate pages. I've previously found all of that content really hard to find and this would have helped me a lot when I first started using Viam. Bravo! |
|
It looks like the following files may have been renamed. Please ensure you set all needed aliases: |
|
🔎💬 Inkeep AI search and chat service is syncing content for source 'Viam Docs' |
4 participants
Still have various links to update but figured makes sense to get eyes on it before investing in link fixes