docs: improve kargo concepts docs #2564
Conversation
Signed-off-by: nitishfy <[email protected]>
✅ Deploy Preview for docs-kargo-akuity-io ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #2564 +/- ##
=======================================
Coverage 50.67% 50.67%
=======================================
Files 278 278
Lines 20516 20516
=======================================
Hits 10397 10397
Misses 9479 9479
Partials 640 640 ☔ View full report in Codecov by Sentry. |
Co-authored-by: Kent Rancourt <[email protected]> Signed-off-by: nitishfy <[email protected]>
nitishfy
force-pushed
the
fix-concepts-docs
branch
from
37b6eeb
to
1ccf4d8
Compare
| **Freight** is Kargo's second most important concept. Frieight generally refers | ||
| to a collection of artifacts that gets promoted together to the next stage. | ||
| A single "piece of freight" is a set of references to one or more versioned | ||
| artifacts, which may include one or more: |
There was a problem hiding this comment.
tbh, I feel this change adds more confusion. We should be careful of unnecessarily using words like "generally," as it implies there are exceptions to what you're about to say. Freight isn't generally a collection of artifacts. Freight is a collection of artifacts. There isn't an exception to that.
The bit about Freight being what moves from stage to stage is already stated just a few lines down from here.
imho, I would revert this change.
| **Freight** is Kargo's second most important concept. Frieight generally refers | |
| to a collection of artifacts that gets promoted together to the next stage. | |
| A single "piece of freight" is a set of references to one or more versioned | |
| artifacts, which may include one or more: | |
| **Freight** is Kargo's second most important concept. A single "piece of | |
| freight" is a set of references to one or more versioned artifacts, which may | |
| include one or more: |
| A **warehouse** is a _source_ of freight. It is where a collection of 'Freight' | ||
| gets stored before the 'Freight' is deployed anywhere. | ||
|
|
||
| A warehouse subscribes to one or more: |
There was a problem hiding this comment.
Even in the real word, I think warehouses are a somewhat fuzzy concept. Is a warehouse a sort of archive where physical things are stored, possibly long-term? Or is it more of a fulfillment/shipping hub? It can be one or the other, or both.
Kargo warehouses are really about fulfillment. I'm not sure it would be accurate to say they store freight. Freight are instances of a CRD. So, really, Kubernetes stores your Freight. The first few sections of this page stay away from technical details. CRDs are not mentioned until later. But I think the statement that warehouses store freight may set the reader up for confusion when they do read about the CRD later.
Improve Kargo concept docs to make the concepts slightly easier to understand