Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

DeviceMotionEvent: Improve explanation of acceleration attributes. #6675

Merged
merged 1 commit into from
Jul 12, 2021
Merged

DeviceMotionEvent: Improve explanation of acceleration attributes. #6675

merged 1 commit into from
Jul 12, 2021

Conversation

rakuco
Copy link
Contributor

@rakuco rakuco commented Jul 8, 2021

accelerationIncludingGravity is a bad name that we unfortunately have to
live with (see w3c/deviceorientation#96). It essentially represents raw
accelerometer data, whose values can be surprising: when a device is at rest
with the screen pointing up, it reports +9.8 in the Z axis rather than 0;
when the device is in free fall, it reports 0 in the Z axis.

Try to explain this in a succint way while also pointing to more detailed
information in related Wikipedia articles. The changes also change a
sentence that said the attribute represented a sum of acceleration on the
device and acceleration caused by gravity. This is confusing because the
DeviceOrientation Event spec defines accelerationIncludingGravity as
acceleration on the device plus an acceleration equal and opposite to
gravity.

While here, be clear that the accelerometer attribute does not include the
effects of gravity, and reference the corresponding Generic Sensor API
interfaces that provide the same data in an arguably better way and with
better names: Accelerometer and LinearAccelerationSensor.

@rakuco rakuco requested a review from a team as a code owner July 8, 2021 11:53
@rakuco rakuco requested review from jpmedley and removed request for a team July 8, 2021 11:53
@github-actions
Copy link
Contributor

github-actions bot commented Jul 8, 2021 •
edited
Loading

Preview URLs

Flaws

None! 🎉

External URLs

URL: /en-US/docs/Web/API/DeviceMotionEvent
Title: DeviceMotionEvent
on GitHub

No new external URLs

URL: /en-US/docs/Web/API/DeviceMotionEvent/accelerationIncludingGravity
Title: DeviceMotionEvent.accelerationIncludingGravity
on GitHub

No new external URLs

URL: /en-US/docs/Web/API/DeviceMotionEvent/acceleration
Title: DeviceMotionEvent.acceleration
on GitHub

No new external URLs

(this comment was updated 2021-07-08 12:00:14.979283)

@rakuco
DeviceMotionEvent: Improve explanation of acceleration attributes.
352391e 
`accelerationIncludingGravity` is a bad name that we unfortunately have to
live with (see w3c/deviceorientation#96). It essentially represents raw
accelerometer data, whose values can be surprising: when a device is at rest
with the screen pointing up, it reports +9.8 in the Z axis rather than 0;
when the device is in free fall, it reports 0 in the Z axis.

Try to explain this in a succint way while also pointing to more detailed
information in related Wikipedia articles. The changes also change a
sentence that said the attribute represented a sum of acceleration on the
device and acceleration caused by gravity. This is confusing because the
DeviceOrientation Event spec defines `accelerationIncludingGravity` as
acceleration on the device plus an acceleration equal and _opposite_ to
gravity.

While here, be clear that the `accelerometer` attribute does not include the
effects of gravity, and reference the corresponding Generic Sensor API
interfaces that provide the same data in an arguably better way and with
better names: `Accelerometer` and `LinearAccelerationSensor`.
@rakuco rakuco force-pushed the improve-devicemotionevent-acceleration-explanation branch from f68594d to 352391e Compare July 8, 2021 11:58
@rakuco
Copy link
Contributor Author

rakuco commented Jul 8, 2021

I'd appreciate some feedback on the text. This API is more than a decade old and it shows; trying to explain these concepts in a simple way can be quite hard!

@rakuco rakuco mentioned this pull request Jul 8, 2021
Closed
@teoli2003 teoli2003 merged commit 7c1301c into mdn:main Jul 12, 2021
@teoli2003
Copy link
Contributor

Thanks a lot, this is much much clearer than before. Any more improvement can be done in a follow-up.

@rakuco rakuco deleted the improve-devicemotionevent-acceleration-explanation branch July 12, 2021 08:26
mfuji09 added a commit to mfuji09/MDN-content that referenced this pull request Jul 12, 2021
@mfuji09
Squashed commit of the following:
4dae73d 
commit 1a288b1
Author: Hamish Willee <hamishwillee@gmail.com>
Date:   Tue Jul 13 01:27:09 2021 +1000

    FF90: In operator can be used with private features (mdn#6786)

    * In operator can be used with private features

    * Update files/en-us/mozilla/firefox/releases/90/index.html

    * Update files/en-us/web/javascript/guide/working_with_private_class_features/index.html

    * Update files/en-us/web/javascript/guide/working_with_private_class_features/index.html

    Co-authored-by: Ruth John <Rumyra@users.noreply.github.com>

commit ca22ef9
Author: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Date:   Mon Jul 12 14:06:48 2021 +0000

    chore(deps): bump @mdn/yari from 0.4.587 to 0.4.591 (mdn#6811)

commit 0f24999
Author: Jason <jason@fry.team>
Date:   Mon Jul 12 09:31:29 2021 -0400

    Fix grammar in PaymentRequest(mdn#6810)

commit ed76f67
Author: Keleti Márton <tejes@hac.hu>
Date:   Mon Jul 12 14:55:27 2021 +0200

    Fix hyphen in BigInt code example (mdn#6807)

commit f8090e9
Author: Hamish Willee <hamishwillee@gmail.com>
Date:   Mon Jul 12 20:05:48 2021 +1000

    FF90: Add info about EXIF intrinsic size (basic) (mdn#6798)

commit fcd44af
Author: Jean-Yves Perrier <jypenator@gmail.com>
Date:   Mon Jul 12 11:13:36 2021 +0200

    Fix default value for Firefox (mdn#6795)

commit 9f395f9
Author: Mudit Bhadouria <mudit5592@gmail.com>
Date:   Mon Jul 12 14:42:06 2021 +0530

    Updating examples in "Inheritance and the prototype chain" (mdn#6803)

    * Updating examples in "Inheritance and the prototype chain"

    There were few instances where a new object was assigned to the prototype property of a function. This is not a good approach. Instead, in order to add a new property, it should be added to the existing prototype of the function.
    For example,
    foo.prototype = {
      foo_prop: "foo val"
    };
    should be
    foo.prototype.foo_prop = "foo val";

    Also, in some places, the constructor function was not being called while being initialized with the new keyword.

    * Removing redundant code

commit 821c317
Author: Michael[tm] Smith <mike@w3.org>
Date:   Mon Jul 12 18:06:46 2021 +0900

    Restore a necessary http (non-https) URL (mdn#6800)

    It seems that mdn@9917877
    (PR mdn#618) inadvertently changed a URL
    that intentionally used an “http” scheme rather than “https”.

    This changes it back to what it should be.

    Fixes mdn#6692

commit d57ebf1
Author: Jean-Yves Perrier <jypenator@gmail.com>
Date:   Mon Jul 12 10:59:12 2021 +0200

    Remove useless * to indicate existence of a note (mdn#6802)

commit 7e49c38
Author: Michael[tm] Smith <mike@w3.org>
Date:   Mon Jul 12 17:25:16 2021 +0900

    Un-link the word “instantiating” in “Working with objects” doc (mdn#6801)

    This change removes a broken link to an anchor for an article section
    which no longer exists. It’s anyway an unnecessary link, since we use
    the word “instantiat(e|ing)” in plenty of other places in the docs,
    without it being hypertext.

    Fixes mdn#6696

commit 7c1301c
Author: Raphael Kubo da Costa <raphael.kubo.da.costa@intel.com>
Date:   Mon Jul 12 10:10:24 2021 +0200

    DeviceMotionEvent: Improve explanation of acceleration attributes. (mdn#6675)

    `accelerationIncludingGravity` is a bad name that we unfortunately have to
    live with (see w3c/deviceorientation#96). It essentially represents raw
    accelerometer data, whose values can be surprising: when a device is at rest
    with the screen pointing up, it reports +9.8 in the Z axis rather than 0;
    when the device is in free fall, it reports 0 in the Z axis.

    Try to explain this in a succint way while also pointing to more detailed
    information in related Wikipedia articles. The changes also change a
    sentence that said the attribute represented a sum of acceleration on the
    device and acceleration caused by gravity. This is confusing because the
    DeviceOrientation Event spec defines `accelerationIncludingGravity` as
    acceleration on the device plus an acceleration equal and _opposite_ to
    gravity.

    While here, be clear that the `accelerometer` attribute does not include the
    effects of gravity, and reference the corresponding Generic Sensor API
    interfaces that provide the same data in an arguably better way and with
    better names: `Accelerometer` and `LinearAccelerationSensor`.

commit 1d4b2fc
Author: Michael[tm] Smith <mike@w3.org>
Date:   Mon Jul 12 16:46:23 2021 +0900

    Fix image 404 in “contextmenu” doc (mdn#6799)

    Fixes mdn#6635

commit dfe264c
Author: Jean-Yves Perrier <jypenator@gmail.com>
Date:   Mon Jul 12 09:28:50 2021 +0200

    Add comma after all “i.e.” cases in JS “Functions” doc (mdn#6796)

commit 832edb2
Author: Michael[tm] Smith <mike@w3.org>
Date:   Mon Jul 12 16:25:22 2021 +0900

    Fix 404 link in “Date formatting using luxon” doc (mdn#6797)

    Fixes mdn#6631

commit a6dc810
Author: Hasith <it17142038@my.sliit.lk>
Date:   Mon Jul 12 11:59:04 2021 +0530

    “User authentication and permissions”﹕Mention custom user models (mdn#6654)

commit a2bc0c1
Author: Roy Hyunjin Han <rhh@crosscompute.com>
Date:   Mon Jul 12 02:22:25 2021 -0400

    Mention Pyramid in “How do you set up a local testing server?” (mdn#6693)

commit d8c31c8
Author: Cheryl Hughey <cherylhughey@hotmail.com>
Date:   Mon Jul 12 01:17:58 2021 -0500

    Update pr-test.yml (mdn#5610)

    Punctuation added to comments for clarity and flow.

commit 83b94d7
Author: Aaron Byrom <aaron.byr@gmail.com>
Date:   Mon Jul 12 16:15:46 2021 +1000

    Drop placeholder text in “ARIA: tabpanel role” doc (mdn#6794)

    The Accessibility concerns and Best practices sections are both placeholder
    text, with the quote "Remove the section if none exist."

commit 448af07
Author: alattalatta <urty5656@gmail.com>
Date:   Mon Jul 12 15:10:03 2021 +0900

    Improve consistency of glossary abbreviations (mdn#6771)

commit fb3bb08
Author: Masahiro FUJIMOTO <mfujimot@gmail.com>
Date:   Mon Jul 12 15:08:59 2021 +0900

    Replace Boolean in fields of FormEventInit dictionary (mdn#6770)

    Replace Boolean with "true or false value" in fields of FormEventInit dictionary because they aren't actually Boolean wrapper objects

commit b9573a4
Author: Jonathan Pool <pool@jpdev.pro>
Date:   Mon Jul 12 02:07:26 2021 -0400

    Add missing restriction to cssText method (mdn#6735)

commit f748f16
Author: Joachim <x775@users.noreply.github.com>
Date:   Mon Jul 12 08:06:39 2021 +0200

    “Arrow function expressions”: Use notecard; add missing colon (mdn#6722)

commit b6f57e5
Author: Jake Thurman <jacob@thurmans.com>
Date:   Mon Jul 12 02:04:06 2021 -0400

    Add Edgium to browser detection sample (mdn#6732)

commit ab04150
Author: Omar <56449814+oasaleh@users.noreply.github.com>
Date:   Mon Jul 12 01:03:17 2021 -0500

    Fix misleading statement in “Introducing asynchronous JavaScript” (mdn#6733)

    Asynchronous functions aren't necessary going to be executed on a different
    thread.

commit 10628e7
Author: ctstacey <51082452+ctstacey@users.noreply.github.com>
Date:   Mon Jul 12 15:59:00 2021 +1000

    clarify return value, remove duplicate description (mdn#6702)

commit b04ce27
Author: Varun Balan <52567863+varun-balan@users.noreply.github.com>
Date:   Mon Jul 12 13:41:51 2021 +0800

    Fix typo in "Promise Terminology Recap" (mdn#6791)

    Just fixing a simple typo I saw. Changed from "a few more time" to "a few more times"

commit 6d82285
Author: Mudit Bhadouria <mudit5592@gmail.com>
Date:   Mon Jul 12 11:02:56 2021 +0530

    Update example in “Inheritance and the prototype chain” (mdn#6751)

commit 42ed216
Author: Dhruv Jain <dhruvjainpenny@gmail.com>
Date:   Mon Jul 12 10:45:02 2021 +0530

    fix: remove duplicate media query list link (mdn#6793)

commit 1027820
Author: Alan <51193876+ConsciousClay@users.noreply.github.com>
Date:   Sun Jul 11 21:11:19 2021 -0700

    fixed punctuation, phrasing, and grammar (mdn#6783)

commit 5f8962a
Author: Alan <51193876+ConsciousClay@users.noreply.github.com>
Date:   Sun Jul 11 21:10:33 2021 -0700

    fixed phrasing (mdn#6780)

commit a4e1fb5
Author: Alan <51193876+ConsciousClay@users.noreply.github.com>
Date:   Sun Jul 11 21:09:48 2021 -0700

    fixed typo (mdn#6781)

commit b1d03b3
Author: Alan <51193876+ConsciousClay@users.noreply.github.com>
Date:   Sun Jul 11 21:07:43 2021 -0700

    fixed grammar (mdn#6779)

commit e2976c3
Author: Jean-Yves Perrier <jypenator@gmail.com>
Date:   Mon Jul 12 02:45:16 2021 +0200

    Fix phone-app to audio-app for consistency (mdn#6728)

commit 5b16a00
Author: Alan <51193876+ConsciousClay@users.noreply.github.com>
Date:   Sun Jul 11 15:08:45 2021 -0700

    Transform a clause in a subordinate one (mdn#6776)

commit 4c61181
Author: Alan <51193876+ConsciousClay@users.noreply.github.com>
Date:   Sun Jul 11 15:06:59 2021 -0700

    Add adverb to make sentence more precise (mdn#6775)

commit b271358
Author: Luke Warlow <projects@warlow.dev>
Date:   Sun Jul 11 19:31:24 2021 +0100

    Remove Experimental_Inline from pseudo classes that are no longer experimental. (mdn#6768)

    Thank you!
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 31, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@teoli2003 teoli2003 teoli2003 approved these changes

@jpmedley jpmedley Awaiting requested review from jpmedley

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@rakuco @teoli2003