Fix/intro grammar #76
Conversation
|
✔️ Deploy Preview for dtcg-tr ready! 🔨 Explore the source changes: 6c0cc14 🔍 Inspect the deploy log: https://app.netlify.com/sites/dtcg-tr/deploys/6144d09a8ee03100070532c4 😎 Browse the preview: https://deploy-preview-76--dtcg-tr.netlify.app/format |
| <p> | ||
| This is a snapshot of the editors’ draft. It is provided for discussion | ||
| only and may change at any moment. Its publication here does not imply | ||
| endorsement of its contents by W3C or the Design Tokens W3C Community | ||
| Group Membership. Don’t cite this document other than as work in | ||
| progress. | ||
| This is a snapshot of the editors’ draft. It is for discussion only and | ||
| may change at any moment. Its publication does not imply endorsement by | ||
| W3C or the Design Tokens W3C Community Group Membership. Don’t cite this | ||
| document other than as work in progress. | ||
| </p> | ||
| <p>This document has been published to facilitate Wide Review.</p> | ||
| <p> | ||
| This document was produced by the Design Tokens W3C Community Group, and | ||
| contributions to this draft are governed by | ||
| The Design Tokens W3C Community Group produced this document. They | ||
| published it to facilitate Wide Review. | ||
| </p> | ||
| <p> | ||
| The | ||
| <a href="https://www.w3.org/community/about/process/cla"> | ||
| Community Contributor License Agreement (CLA) </a | ||
| >, as specified by the | ||
| >governs contributions to this draft, as specified by the | ||
| <a href="https://www.w3.org/community/about/process/#cgroups" | ||
| >W3C Community Group Process</a | ||
| >. |
There was a problem hiding this comment.
This section is boilerplate from the W3C that you'll generally find untouched or very lightly edited in drafts. Not sure we should optimize for readability or consistency.
There was a problem hiding this comment.
I'd lean towards consistency in this instance. After all, we're trying to align with W3C's tooling, process and writing style elsewhere.
|
I agree with the intent, but think an over-reliance on Hemingway is detrimental to the readability and clarity of this doc. I find that following Hemingway's suggestions too closely leads to a succession of tiny sentences that can read as quite dry, and breaks the flow of otherwise very readable content. In one of the sentences, all jargon was removed in an undesirable lossy rewrite. My guidance is to use Hemingway sparingly, and take its suggestions for what they are: suggestions. 👍🏻 It's useful to avoid very long sentences, repetitions, and spot passive voice that would read better as active. 👎🏻 It warns about jargon that's actually important in our context: technical reports are aimed at experts who rely on this vocabulary to derive precise meaning. (Grammarly allows to specify the target audience, tone, level of formality… I personally find it better than Hemingway for professional writing like technical proposals, and still use Hemingway for blog posts) |
| <p> | ||
| This is a snapshot of the editors’ draft. It is provided for discussion | ||
| only and may change at any moment. Its publication here does not imply | ||
| endorsement of its contents by W3C or the Design Tokens W3C Community | ||
| Group Membership. Don’t cite this document other than as work in | ||
| progress. | ||
| This is a snapshot of the editors’ draft. It is for discussion only and | ||
| may change at any moment. Its publication does not imply endorsement by | ||
| W3C or the Design Tokens W3C Community Group Membership. Don’t cite this | ||
| document other than as work in progress. | ||
| </p> | ||
| <p>This document has been published to facilitate Wide Review.</p> | ||
| <p> | ||
| This document was produced by the Design Tokens W3C Community Group, and | ||
| contributions to this draft are governed by | ||
| The Design Tokens W3C Community Group produced this document. They | ||
| published it to facilitate Wide Review. | ||
| </p> | ||
| <p> | ||
| The | ||
| <a href="https://www.w3.org/community/about/process/cla"> | ||
| Community Contributor License Agreement (CLA) </a | ||
| >, as specified by the | ||
| >governs contributions to this draft, as specified by the | ||
| <a href="https://www.w3.org/community/about/process/#cgroups" | ||
| >W3C Community Group Process</a | ||
| >. |
There was a problem hiding this comment.
I'd lean towards consistency in this instance. After all, we're trying to align with W3C's tooling, process and writing style elsewhere.
| It is often desirable for design system teams to integrate such tools | ||
| together, so that design token data can flow between design and | ||
| development tools. For example: | ||
| Design tokens establish a common vocabulary across organizations. They |
There was a problem hiding this comment.
Whoa! Harsh edit :-P
I'm all for making things more concise and using plain English, but I think the specific examples of tools that might use tokens are useful here to set context.
| </p> | ||
| <ul> |
There was a problem hiding this comment.
If we leave the above bit as is, then we need to keep this list too.
| </p> | ||
| <p> | ||
| This specification aims to facilitate better interoperability between |
There was a problem hiding this comment.
I think the original is better here. The edited version is too vague and "largest goal" just sounds weird to me.
|
Good feedback. Declining PR. |
I've used https://hemingwayapp.com to edit the intro section for conciseness.
Here's the before and after for comparison.
References #66