Update service declaration documentation #163
Conversation
✅ Deploy Preview for open-terms-archive-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
content/terms/explanation/_index.md
Outdated
| @@ -0,0 +1,4 @@ | |||
| --- | |||
| title: Explanation | |||
There was a problem hiding this comment.
We have a plural consistency issue: “Tutorials” and “Guidelines” is plural, but “Explanation” and “How to” is singular.
I would be in favor of having every section title in plural.
There was a problem hiding this comment.
In diataxis, "tutorials" and "how-to guides" are plural whereas "reference" and "explanation" are singular, and it makes sense for me.
So i'm in favor of having "tutorials", "how-to guides" and "guidelines" and "explanation" and "reference"
What do you think @MattiSG @clementbiron?
There was a problem hiding this comment.
I personally find it strange that these are singular and would prefer to have everything plural.
There was a problem hiding this comment.
After IRL discussion, let's go with all plural
| >}} | ||
| ```yaml | ||
| description: > |
There was a problem hiding this comment.
Why do we add the key? Other examples give only the value as example.
There was a problem hiding this comment.
When dealing with complex multiline examples, I find it more readable to include the key. However, for single values, it doesn’t seem necessary.
| To that end, a range selector is a JSON object containing two keys out of the four that are available: `startBefore`, `startAfter`, `endBefore` and `endAfter`. | ||
| To facilitate cross-service comparisons and ensure consistency, a standardized list of term types is maintained in a [dedicated repository](https://github.com/OpenTermsArchive/terms-types). | ||
|
|
||
| Please note, the terms type may differ from the exact name provided by the service, but it should align with the underlying commitment. For example, some providers might call “Terms and Conditions” or “Terms of Use” what some others call “Terms of Service”. |
There was a problem hiding this comment.
| Please note, the terms type may differ from the exact name provided by the service, but it should align with the underlying commitment. For example, some providers might call “Terms and Conditions” or “Terms of Use” what some others call “Terms of Service”. | |
| Please note that the terms type may differ from the exact name provided by the service, but it should align with the underlying commitment. For example, some providers might call “Terms and Conditions” or “Terms of Use” what some others call “Terms of Service”. The standardized name should be used. |
| - a CSS selector string. See the [CSS Selectors specification](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) | ||
| - a range selector object. See the [range selector]({{< relref \"#range-selector\" >}}) section | ||
| - an array of those` |
There was a problem hiding this comment.
| - a CSS selector string. See the [CSS Selectors specification](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) | |
| - a range selector object. See the [range selector]({{< relref \"#range-selector\" >}}) section | |
| - an array of those` | |
| - A CSS selector string. See the [CSS Selectors specification](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors). | |
| - A range selector object. See the [range selector]({{< relref \"#range-selector\" >}}) section. | |
| - An array of those.` |
| To capture content starting from and including a privacy section up until but excluding the footer: | ||
|
|
||
| ```sh | ||
| npm run lint [$service_id [$another_service_id …]] | ||
| ```json | ||
| { | ||
| "startBefore": "#privacy-section", |
There was a problem hiding this comment.
| To capture content starting from and including a privacy section up until but excluding the footer: | |
| ```sh | |
| npm run lint [$service_id [$another_service_id …]] | |
| ```json | |
| { | |
| "startBefore": "#privacy-section", | |
| To capture content starting from and including a hypothetical “European Economic Area privacy” section up until the footer (but excluding the footer): | |
| ```json | |
| { | |
| "startBefore": "#privacy-eea", |
| </ol> | ||
| </div> | ||
|
|
||
| <!-- Sub Navigation --> |
There was a problem hiding this comment.
Why isn't the breadcrumbs navigation enough to illustrate the relevance? I feel that we make the example bigger than necessary 🙂
| } | ||
| ``` | ||
|
|
||
| This range selector will select the terms content between the main title and the footer element. |
There was a problem hiding this comment.
I love this page and the intention to provide an example! This specific one seems to me a bit risky in that it shows how to use range selectors in a case where a select: main + remove: div would be more efficient. Is there any way we can make the example clearer? 🙂
There was a problem hiding this comment.
I feel that this is more of a Reference than an Explanation… This explains how to write filters more than it gives the background knowledge on their usage.
Co-authored-by: Matti Schneider <[email protected]>
Co-authored-by: Matti Schneider <[email protected]>
Follow Diataxis
There was a problem hiding this comment.
What a great improvement, congrats @Ndpnt for leading this work and thanks @clementbiron too for delivering it!
No description provided.