Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add sensor user journey #2986

Merged
merged 15 commits into from
Jun 21, 2024
Merged

Add sensor user journey #2986

merged 15 commits into from
Jun 21, 2024

Conversation

npentrel
Copy link
Collaborator

@npentrel npentrel commented Jun 5, 2024 •
edited
Loading

Please review for content not design. I know there's some issues when viewing on small screens.

These are the how-tos:

They will replace:

@viambot viambot added the safe to build This pull request is marked safe to build from a trusted zone label Jun 5, 2024
@viambot
Copy link
Member

viambot commented Jun 5, 2024 •
edited
Loading

Overall readability score: 52.98 (🔴 -0.09)

File Readability
_index.md 100 (🟢 +0)
data-client.md 71.46 (🟢 +0.08)
changelog.md 36.19 (🟢 +0.02)
ultrasonic.md 39.31 (🟢 +0)
cli.md 71.83 (🟢 +0.15)
bme280.md 43.04 (🟢 +0)
ds18b20.md 38.52 (🟢 +0)
fake.md 34.56 (🟢 +0)
sensirion-sht3xd.md 42.2 (🟢 +0)
ultrasonic.md 24.83 (🟢 +0)
control.md 16.55 (🟢 +0)
_index.md 19.1 (🟢 +0)
_index.md 61.22 (🟢 +0)
performance-metrics.md 52.98 (🟢 +0)
cloud-sync.md 55.15 (🟢 +0)
view.md 63.38 (🟢 +0)
visualize-data-grafana.md 50.53 (🔴 -0.05)
_index.md 32.68 (🔴 -0.61)
collect-sensor-data.md 45.46 (-)
deploy-code.md 47.93 (🟢 +0)
image-data.md 56.22 (🟢 +0)
sensor-data-query-sdk.md 29.18 (-)
sensor-data-query.md 29.22 (-)
sensor-data-visualize.md 40.92 (-)
sensor-control.md 58.51 (🟢 +0)
install-cli.md 49.63 (-)
query-data.md 42.24 (-)
View detailed metrics

🟢 - Shows an increase in readability
🔴 - Shows a decrease in readability

File Readability FRE GF ARI CLI DCRS
_index.md 100 100 6 6 6 4.9
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
data-client.md 71.46 42.27 6.32 12 11.76 5.4
  🟢 +0.08 🟢 +0 🟢 +0 🟢 +0 🟢 +0.06 🟢 +0
changelog.md 36.19 33.07 15.05 18.9 13.07 7.55
  🟢 +0.02 🟢 +0 🟢 +0.01 🟢 +0 🟢 +0 🟢 +0
ultrasonic.md 39.31 40.99 13.29 17.4 13.81 8.28
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
cli.md 71.83 46.67 7.9 10.7 10.84 5.66
  🟢 +0.15 🟢 +0 🟢 +0 🟢 +0.1 🟢 +0 🟢 +0
bme280.md 43.04 39.23 11.66 15.1 14.67 8.56
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
ds18b20.md 38.52 30.67 12.21 15.4 15.42 8.77
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
fake.md 34.56 34.26 12.8 18.3 15.37 8.58
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
sensirion-sht3xd.md 42.2 39.43 11.67 15.4 15.13 8.49
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
ultrasonic.md 24.83 16.62 13.25 20.3 17.35 8.69
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
control.md 16.55 0 14.8 22 19 8.09
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
_index.md 19.1 14.53 16.3 22 15.91 8.6
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
_index.md 61.22 50.77 10.45 13.1 11.08 6.62
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
performance-metrics.md 52.98 45.66 10.71 13.3 13.05 7.83
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
cloud-sync.md 55.15 48.74 11.93 14 11.49 7.03
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
view.md 63.38 52.8 10.48 11.4 9.98 7.29
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
visualize-data-grafana.md 50.53 32.53 11.43 15.1 13 6.74
  🔴 -0.05 🟢 +0 🔴 -0.01 🟢 +0 🟢 +0 🔴 -0.01
_index.md 32.68 42.04 15.74 19.8 12.43 8.61
  🔴 -0.61 🟢 +0 🟢 +0 🔴 -0.3 🔴 -0.12 🟢 +0
collect-sensor-data.md 45.46 45.9 12.99 17.8 11.84 7.46
  - - - - - -
deploy-code.md 47.93 44.27 13.49 16.2 11.03 7.42
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
image-data.md 56.22 48.54 11.25 15.2 10.57 6.91
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
sensor-data-query-sdk.md 29.18 32.16 15.51 21.4 12.95 8.36
  - - - - - -
sensor-data-query.md 29.22 29.72 15.72 22 13.59 7.56
  - - - - - -
sensor-data-visualize.md 40.92 29.28 13.12 17.7 13.29 7.36
  - - - - - -
sensor-control.md 58.51 56.96 9.44 11.2 12.06 8.75
  🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0 🟢 +0
install-cli.md 49.63 46.3 13.14 15.4 10.86 7.62
  - - - - - -
query-data.md 42.24 32.12 11.81 17.5 14.21 7.48
  - - - - - -

Averages:

  Readability FRE GF ARI CLI DCRS
Average 52.98 45.69 11.15 12.62 12.11 8.32
  🔴 -0.09 🔴 -0.05 🔴 -0.02 🔴 -0.03 🟢 +0 🟢 +0
View metric targets
Metric Range Ideal score
Flesch Reading Ease 100 (very easy read) to 0 (extremely difficult read) 60
Gunning Fog 6 (very easy read) to 17 (extremely difficult read) 8 or less
Auto. Read. Index 6 (very easy read) to 14 (extremely difficult read) 8 or less
Coleman Liau Index 6 (very easy read) to 17 (extremely difficult read) 8 or less
Dale-Chall Readability 4.9 (very easy read) to 9.9 (extremely difficult read) 6.9 or less

@npentrel npentrel force-pushed the user-journeys branch 5 times, most recently from bcf8e5a to 6dc46be Compare June 5, 2024 19:39
@npentrel npentrel changed the title Draft for one user journey Add sensor user journey Jun 6, 2024
@npentrel npentrel force-pushed the user-journeys branch 2 times, most recently from 6bc301d to 6795854 Compare June 7, 2024 20:06
sguequierre
sguequierre previously requested changes Jun 7, 2024
View reviewed changes
Copy link
Collaborator

@sguequierre sguequierre left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Couple typos/periods but mostly looks great!

docs/use-cases/sensor-data-query.md Outdated Show resolved Hide resolved
docs/use-cases/sensor-data-query.md Outdated Show resolved Hide resolved
docs/use-cases/sensor-data-query.md Outdated Show resolved Hide resolved
docs/use-cases/sensor-data-query.md Outdated Show resolved Hide resolved
docs/use-cases/sensor-data-query.md Outdated Show resolved Hide resolved
docs/use-cases/sensor-data-visualize.md Outdated Show resolved Hide resolved
static/include/how-to/gather-sync-sensor.md Outdated
{{<imgproc src="/services/icons/data-management.svg" class="fill alignleft" style="max-width: 150px" declaredimensions=true alt="Configure the data management service">}}
**1. Add the data management service**

On your machine's **CONFIGURE** tab, add the **data management** service.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe more steps here like with the sensors?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

static/include/how-to/gather-sync-sensor.md Outdated Show resolved Hide resolved
static/include/how-to/gather-sync-sensor.md Outdated Show resolved Hide resolved
static/include/how-to/gather-sync-sensor.md Outdated Show resolved Hide resolved
npentrel
npentrel commented Jun 17, 2024
View reviewed changes
docs/use-cases/collect-sensor-data.md Outdated
For example, you can configure data capture for several sensors on one machine, or for serveral sensors across multiple machines, to report the ambient operating temperature.
You can then run queries against that data to search for outliers or edge cases, to analyze how the ambient temperature affects your machines' operation.

{{< alert title="Content" color="tip" >}}
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
{{< alert title="Content" color="tip" >}}
{{< alert title="In this page" color="tip" >}}

JessamyT
JessamyT reviewed Jun 21, 2024
View reviewed changes
Copy link
Collaborator

@JessamyT JessamyT left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

High level I'm wondering if we can/should actually eliminate the visualization one since it doesn't really guide the user that much? Since it'd need to be specific to a given tool to actually provide step-by-step instructions, and because it relies on the data query use case anyway?

docs/use-cases/sensor-data-query-sdk.md Outdated Show resolved Hide resolved
docs/use-cases/sensor-data-query-sdk.md Outdated Show resolved Hide resolved
docs/use-cases/sensor-data-query.md Outdated Show resolved Hide resolved
docs/use-cases/sensor-data-query.md Outdated Show resolved Hide resolved
docs/use-cases/sensor-data-visualize.md Outdated Show resolved Hide resolved
docs/use-cases/sensor-data-visualize.md Outdated
Some third-party visualization tools support the ability to directly query your data within their platform to generate more granular visualizations of specific data.
You might use this functionality to visualize only a single day's metrics, limit the visualization to a select machine or component, or to isolate an outlier in your reported data, for example.

While every third-party tool is different, you would generally query your data using either {{< glossary_tooltip term_id="sql" text="SQL" >}} or {{< glossary_tooltip term_id="mql" text="MQL" >}}. See the following guide on [querying sensor data](/use-cases/sensor-data-query/) for more information.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

! Wait, isn't this a bit circular? Why do we have this page if they just need to follow the query sensor data guide anyway?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that's fairly common with this style of choose your own path content. You cannot assume that they've read the other content. And if they have, they'll think "oh ok, I've reached the end of what I can get from this info"

docs/use-cases/sensor-data-visualize.md Outdated Show resolved Hide resolved
docs/use-cases/sensor-data-visualize.md Outdated Show resolved Hide resolved
docs/use-cases/sensor-data-query-sdk.md Show resolved Hide resolved
docs/use-cases/sensor-data-query-sdk.md Outdated
weight: 31
type: "docs"
images: ["/services/icons/data-query.svg"]
description: "Query sensor data that you have synced to the Viam app using the data management service with SQL or MQL."
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the exact same description as for the non-SDK one

npentrel and others added 11 commits June 21, 2024 11:15
@npentrel
Copy link
Collaborator Author

npentrel commented Jun 21, 2024 •
edited
Loading

High level I'm wondering if we can/should actually eliminate the visualization one since it doesn't really guide the user that much? Since it'd need to be specific to a given tool to actually provide step-by-step instructions, and because it relies on the data query use case anyway?

I think that's a good observation, possibly the wrong conclusion to eliminate though. We want to show people that you can visualize. I think instead we probably want to pull in the Grafana example here but I don't want to do that in this PR. I'll make a ticket.

@viambot
Copy link
Member

viambot commented Jun 21, 2024

You can view a rendered version of the docs from this PR at https://docs-test.viam.dev/2986

@npentrel
Copy link
Collaborator Author

I'm going to merge this now and we can do further review in a separate ticket

@npentrel npentrel merged commit 100d6a0 into viamrobotics:main Jun 21, 2024
9 checks passed
@npentrel npentrel deleted the user-journeys branch June 21, 2024 11:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@JessamyT JessamyT JessamyT left review comments

@erh erh Awaiting requested review from erh

@loopDelicious loopDelicious Awaiting requested review from loopDelicious

@sguequierre sguequierre Awaiting requested review from sguequierre

Assignees
No one assigned
Labels
safe to build This pull request is marked safe to build from a trusted zone
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@npentrel @viambot @sguequierre @JessamyT