bmorelli25
commented
2 years ago 1) 👍
2) I think it makes sense to keep the doc link as it explains both methods of installing Elastic Agent. So with Option 1, the first paragraph would look like this (links bolded)
These steps configure and enroll the Elastic Agent in Fleet to automatically deploy updates and centrally manage the agent. As an alternative to Fleet, advanced users can run agents in standalone mode. For additional guidance, see our installation docs.
Maybe this isn't important, but it's not clear to me that the standalone mode link isn't a doc link. So it seems like we have back-to-back documentation links. Can/should we change the wording of the standalone sentence to clearly explain that users are being linked to a new Kibana workflow and not docs?
3) 👍
dedemorton
mdbirnstiehl
elasticmachine
hop-dev
The documentation links in the new step-based workflow (added in https://github.com/elastic/kibana/pull/132809) point to pages that may be confusing to new users. When the user follows the links, they'll see steps and a screenshot that does not match the UI they're using.
As a quick fix, I propose that we modify the links. This might be difficult if we are reusing code, but let's decide what works best for the user. Here's my proposal:
Note that these recommendations are based on the original design, which has changed, but it sounds like the links still need to be updated.
1) On the "Ready to add your first integration" page:
Why? It's premature to describe installation options here. If users need to access the docs at this point, they're probably asking questions like: What is Elastic Agent? What are integrations?
2) On the "Install Elastic Agent" page:
Option 1:
Why? Sending users directly to the topic about installing Fleet-managed agents may be confusing to new users. When the user follows the link, they'll see steps and a screenshot that does not match the onboarding UI they're using. Sending them to the top-level topic in the installation docs helps them learn more about Fleet vs standalone mode, and they can access other useful topics related to installation. They might still drill down into the specific topics and be confused, though.
Option 2:
Remove the sentence entirely and do not link to the installation docs from the step-based workflow.
3) On the "Install Elastic Agent" page for standalone mode:
Delete the sentence that links to the installation docs.
Why? Sending users directly to the topic about installing standalone agents may be confusing to new users. When users follow the link, they will see steps and a screenshot that doesn't match the onboarding UI they're using. Also because the standalone content was written with the assumption that users might not be using Fleet at all, the steps are quite different.
Describe a specific use case for the feature:
New users onboarding to Elastic need docs that support that experience and match what they see in the UI.