Use case guide for Log Workspaces in the retail industry #29504
Conversation
estherk15
changed the base branch from
master
to
yuliyambg/workspaces_retail_example
estherk15
changed the base branch from
yuliyambg/workspaces_retail_example
to
master
Preview links (active after the
|
|
Opened Jira card DOCS-11030 for an editorial review. |
📝 Documentation Team Review RequiredThis pull request requires approval from the @DataDog/documentation team before it can be merged. Please ensure your changes follow our documentation guidelines and wait for a team member to review and approve your changes. |
There was a problem hiding this comment.
Looks great, Esther! I made some comments about clarifying the action items for customers to help them follow along, but that's without having a ton of context about Log Workspaces, so it may or may not make sense 😅 Let me know what you think and how I can help with getting this out the door, as always!
|
|
||
| ### 1. Inventory data source | ||
|
|
||
| In this example, configure a logs query to filter for an inventory service, including stock levels, product IDs, and threshold levels for each store location. |
There was a problem hiding this comment.
Because this is a guide that says it will demonstrate how to do something, I found these parts a bit confusing. It's a little hard to put my finger on why, but I think it's because they look like examples of something that is completed, which isn't necessarily inappropriate for docs, but the context around it made me expect instructions with some more detail about what a user is supposed to do.
It could also be because the headings made me think that the instructions would be about setting up data sources, but these look like filters to return data, which to me feel like different things. Maybe they feel like more similar concepts when you're more familiar with the source material? If I were a user who were trying to mimic your use case, I think I'd be confused about whether I was supposed to set up the actual systems that send my store's data to Datadog, or if this guide was just about displaying that data in a workspace. Maybe it just needs some more explicit linking to docs that will more clearly take them through any of the processes they find unfamiliar?
There was a problem hiding this comment.
After finishing the page and coming back, I noticed later on how useful it was to include queries that are copyable, which is a nice handy sign that users are supposed to take that part and use it themselves. I'm not sure what would be relevant in these examples, but similar "hey use this!" examples for stuff like search terms might make it easier for customers to understand what you've done so they can start mimicking it themselves.
|
|
||
| {{< img src="/logs/workspace/use_cases/analyze_inventory_across_regions/retail_analysis_cell.png" alt="SQL analysis results showing products with low stock levels and high sales quantities" caption="Analysis cell results identifying products that need restocking based on low inventory and high sales volume." style="width:100%;" >}} | ||
|
|
||
| {{% collapse-content title="Query breakdown" level="h4" expanded=false %}} |
There was a problem hiding this comment.
I might consider putting the query breakdown right next to the query rather than splitting them up with an image - that way, if someone is confused, they can give themselves a little more context sooner :)
| {{< img src="/logs/workspace/use_cases/analyze_inventory_across_regions/retail_location_analysis_cell.png" alt="SQL query joining inventory data with store location reference table to analyze sales by geographic region" style="width:100%;" >}} | ||
|
|
||
| {{% collapse-content title="Query breakdown" level="h4" expanded=false %}} | ||
| This query: |
There was a problem hiding this comment.
I liked the specificity of how the previous query was explained, so I could understand what each operator was doing. I don't think it's strictly necessary to do the exact same thing here again, but for someone who needs a query breakdown, the descriptions of what the different functions do could help them tweak it for their needs!
What does this PR do? What is the motivation?
Merge instructions
Merge readiness:
For Datadog employees:
Merge queue is enabled in this repo. Your branch name MUST follow the
<name>/<description>convention and include the forward slash (/). Without this format, your pull request will not pass in CI, the GitLab pipeline will not run, and you won't get a branch preview. Getting a branch preview makes it easier for us to check any issues with your PR, such as broken links.If your branch doesn't follow this format, rename it or create a new branch and PR.
To have your PR automatically merged after it receives the required reviews, add the following PR comment:
Additional notes