Weave basics docs revamp DOCS-1896#2193
Conversation
… a standalone page moved under integrations. cleanup of Overview page to be more Overviewy.
|
Images automagically compressed by Calibre's image-actions ✨ Compression reduced images by 73.8%, saving 96.5 KB.
|
📚 Mintlify Preview Links✨ Added (11 total)📄 Pages (11)
📝 Changed (9 total)📄 Pages (8)
⚙️ Other (1)
🗑️ Deleted (4 total)View deleted files🖼️ Images (4)
🤖 Generated automatically when Mintlify deployment succeeds |
🔗 Link Checker Results✅ All links are valid! No broken links were detected. Checked against: https://wb-21fd5541-weave-basics-docs-1896.mintlify.app |
dbrian57
left a comment
dbrian57
left a comment
There was a problem hiding this comment.
This looks really great! There are a few comments inline that should be pretty easy fixes.
I also have some thoughts for our next pass through this stuff. Thinking about this from a mental-model building standpoint, I think:
- We should do a better job of conceptualizing Ops, Traces, and Calls in the opening doc (this is probably outside the scope of this PR, though).
- We use "tracing" and "tracking" interchangeably throughout our docs, and I think we should standardize on using one or the other. I think "tracing" and "traces" is the better term to use, imo. I added comments related to this on a few doc titles.
Would love to know your thoughts on this stuff!
| @@ -49,1176 +37,12 @@ A **Call** is a logged execution of an Op. Every time an Op runs, Weave creates | |||
| - Parent-child relationships (for nested calls) | |||
| - Any errors that occurred | |||
|
|
|||
| Calls form the backbone of Weave's tracing system and provide the data for debugging, analysis, and evaluation. | |||
| Calls show up as **Traces** in the Weave UI and provide the data for debugging, analysis, and evaluation. | |||
|
|
|||
|
|
|||
| Calls are similar to spans in the [OpenTelemetry](https://opentelemetry.io) data model. A Call can: | |||
| - Belong to a Trace (a collection of calls in the same execution context) | |||
| - Have parent and child Calls, forming a tree structure | |||
|
|
|||
There was a problem hiding this comment.
Minor thing, and we can do this later, but I think we should link to the Call schema doc here. I think a lot of people want to know what they can get back from a trace and what the data structure looks like. Ideally, I'd put a sample Call object here, but they're large and kinda ugly, so just linking to schema would probably be good.
| @@ -0,0 +1,291 @@ | |||
| --- | |||
| title: "Create Calls" | |||
There was a problem hiding this comment.
I think we need to reframe this page a little bit to be something like, "Trace your code" or "Create traces". All of these methods emit traces that contain calls.
There was a problem hiding this comment.
excellent point!
Co-authored-by: Dan Brian <daniel.brian@gmail.com>
Co-authored-by: Dan Brian <daniel.brian@gmail.com>
|
Images automagically compressed by Calibre's image-actions ✨ Compression reduced images by 5.6%, saving 1.9 KB.
|
Co-authored-by: Dan Brian <daniel.brian@gmail.com>
Co-authored-by: Dan Brian <daniel.brian@gmail.com>
2 participants
Description
Massive rework of 'Basics' page that is 1224 lines long of chaos, containing "engineering-speak".
Divided into conceptual pages, diffing against other existing content and removing only when closely matched.
Attempted grouping/reordering of ToC/IA.
A lot of cleanup in terms of ordering and ensuring surrounding content has a single concept per page. I call out a large number of these in the COMMENTS ON THE TICKET. https://wandb.atlassian.net/browse/DOCS-1896
Pls read the comments on the ticket for a (sorry, large) number of additional things that prb warrant discussion/decision/improvement still.
Note, i'd start at the bottom (oldest first), but there is a huge chunk about me working out additional details regarding the schema page (as I felt it was poorly adequate in details for the user). I'll prb ask Scott to review that one.
Testing
mint dev)mint broken-links)Related issues
Mintlify
0 threads from 0 users in Mintlify