Add glossary to user manual docs #1091
Conversation
|
goddamnit, that was premature apparently. fixing now... |
|
Okay, ready to go! |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1091 +/- ##
=======================================
Coverage 54.69% 54.69%
=======================================
Files 105 105
Lines 7696 7696
=======================================
Hits 4209 4209
Misses 3228 3228
Partials 259 259 ☔ View full report in Codecov by Sentry. |
docs/src/user-manual/glossary.md
Outdated
| format specifications, smaller file sizes, widespread adoption and support | ||
| (particularly in web browsers), high compression rates, etc. Access derivatives | ||
| are typically used in the creation of **Dissemination Information Packages | ||
| (DIPs)**. |
There was a problem hiding this comment.
Bullet formatting went a bit funny here
There was a problem hiding this comment.
Good catch, fixed
docs/src/user-manual/glossary.md
Outdated
|
|
||
| A preservation-relevant action that involves at least one **object** and/or | ||
| **agent**. Events are typically captured in the preservation **metadata** of a | ||
| **package** during a preservation work**flow using the |
There was a problem hiding this comment.
work**flow should be **workflow**
There was a problem hiding this comment.
@fiver-watson I have requested many changes, but do not despair for they are all small changes. :)
| @@ -0,0 +1,368 @@ | |||
| # Glossary | |||
|
|
|||
| **NOTE**: This glossary of terms outlines the domain-specific language used when | |||
There was a problem hiding this comment.
I don't think NOTE: is necessary as the text nicely explains the purpose of the Glossary.
|
|
||
| ## Agent | ||
|
|
||
| An actor (human, machine, or software) associated with one or more **events** |
There was a problem hiding this comment.
I thought the agent actively initiates an event, rather than just being associated with the event?
There was a problem hiding this comment.
This one I am less in agreement with. I was trying to avoid getting too detailed, but in the PREMIS Data Dictionary for example, An Agent:
May hold or grant one or more Rights.
May carry out, authorize, or compel one or more Events.
May create or act upon one or more Objects through an Event or with respect to a Rights statement.
So, much like in archival descriptions, an actor is not always the creator.
| ## Archival Information Package (AIP) | ||
|
|
||
| A type of package derived from a **Processing Information Package (PIP)** that | ||
| is transformed during a preservation **workflow** into one or more AIPs, |
There was a problem hiding this comment.
This definition is circular. I think "...into one or more AIPs," should be cut from this paragraph. The detail that more than one AIP can be produced from a single PIP can be added to one of the subsequent paragraphs.
| is transformed during a preservation **workflow** into one or more AIPs, | ||
| depending on the **preservation policies** defined in the **preservation engine**. | ||
|
|
||
| An AIP is the output of the **preservation engine**, consisting of one or more |
There was a problem hiding this comment.
Hmm, maybe this general definition of an AIP should be the first paragraph?
There was a problem hiding this comment.
ok, i have tried rewording the whole AIP definition to avoid tautology a bit more.
|
|
||
| ## Child workflow | ||
|
|
||
| Child workflows are a feature of the [workflow engine](#workflow-engine), |
There was a problem hiding this comment.
I think it would be better to start with a general definition of a child workflow, without limiting the definition to a feature of the workflow engine. Something like "A child workflow is an ancillary workflow that is spawned by a parent workflow." There are other ways to create and run a child workflow besides Temporal's child workflow mechanism.
There was a problem hiding this comment.
ok, i have taken your advice and tried rewording the definition a bit. That said, while i agree that it's not just a Temporal feature, this was part of the whole reason I reworked the Components docs to be more general. Workflows in general are going to be managed by some kind of "workflow engine" in Enduro, regardless of whether it's Cadence, Temporal, or something else. If we ever found a need and a way to run workflows and child workflows in the Enduro stack outside of the workflow engine, then I had thought that would be a big enough change to warrant updating the definition.
In any case, I removed the reference to the workflow engine from this definition.
|
|
||
| ## Intellectual entity | ||
|
|
||
| The [PREMIS](https://www.loc.gov/standards/premis/) 3 Data Dictionary defines an |
There was a problem hiding this comment.
The "3" looks so lonely outside the hyperlink. 🥺 Maybe "The PREMIS v3 Data Dictionary defines..."?
|
|
||
| An **intellectual entity** describing a type of collection, composed of a set of | ||
| **files** and related **metadata**, assembled together for a particular purpose. | ||
| A package will typically contain one or more **objects**, zero or more |
There was a problem hiding this comment.
By the definition of "Object" above a package must always contain one or more objects.
There was a problem hiding this comment.
sure... but adding "must" and "may" gets a bit complex. I just removed the word "typically" - does that work?
|
|
||
| ## Preservation processing | ||
|
|
||
| A phase in a preservation |
There was a problem hiding this comment.
Also should "preservation workflow" be bold?
There was a problem hiding this comment.
lol i missed a lot of terms that should have been bolded in that one. Fixed.
| workflow describing all the tasks that occur after Ingest, when a PIP is sent to | ||
| the preservation engine for transformation into one or more AIPs. Prior to final | ||
| bagging, compression, and storage, any AIPs created during ingest may also | ||
| undergo any additional Post-ingest activities defined in the system. Examples of |
There was a problem hiding this comment.
"post-ingest" shouldn't be capitalized.
|
|
||
| ## Watched directory | ||
|
|
||
| A filesystem directory used that is configured with a small command-line utility |
There was a problem hiding this comment.
I think this can be shortened to "A filesystem directory that is monitored for changes (e.g. adding, deleting, or renaming a file), and where such a change may trigger one or more subsequent actions (e.g. preservation processing)."
|
Oh, this was merged already. Nevermind. :( |
|
Sorry @djjuhasz - wasn't sure if you wanted to get into the nitty gritty of domain stuff, so after sara reviewed and approved, I merged it... but it's good feedback - i can use it on a new PR. Thanks for taking the time! |
Modified the glossary developed for SFA for general use in the documentation. I mentioned this to @sallain before pushing, but a couple notes on some of the decisions made here:
Looking forward to feedback!