Add API overview page for Device Orientation Events

wbamberg commented 4 years ago

GroupData.json lists "Device Orientation Events" as a Web API with the following contents:

        "Device Orientation Events": {
            "guides":     [ "/docs/Web/API/Detecting_device_orientation" ],
            "interfaces": [ "DeviceAcceleration",
                            "DeviceMotionEvent",
                            "DeviceOrientationEvent",
                            "DeviceRotationRate" ],
            "methods":    [],
            "properties": [],
            "events":     [ "Window: deviceorientation",
                            "Window: compassneedscalibration",
                            "Window: devicemotion" ]
        },

...but it doesn't have an API overview page. We should write a page and add the "overview" property to GroupData.

himanshugarg commented 3 years ago

How about this?

teoli2003 commented 3 years ago

This is the guide that is listed in GroupData.json above and has been moved under Events/ as they were no overview page. Once the overview page is created, it will be move under it.

sideshowbarker commented 2 years ago

Given there’s not be any activity on this in more than two years, I suggest we consider closing it for now rather than continuing to keep it open indefinitely.

And in the interest of trying out a way to keep track of issues we’ve closed that are candidates for being re-opened, I created a backlog label — https://github.com/mdn/content/issues?q=label%3Abacklog. (I don’t feel strongly about the label name; it’s somewhat arbitrary — so if anybody has a better suggestion, we could just change it.)

I recognize that the downside of closing issues that we haven’t yet merged any changes for is that the issues aren’t going to be easily discoverable by contributors coming in looking for something to work on. But for issues that are more than two years old, it seems reasonable to assume that something’s going to change and those will end up being the issues that other contributors would end up choosing to work on.

So for these kinds of issues, it seems like the project maintainers just need to have some internal way of keeping track of them — which the backlog (or whatever name) label allows us to do.

wbamberg commented 2 years ago

I have the same comment here as for https://github.com/mdn/content/issues/2647#issuecomment-1164636473.

If we close these and add a label, that just gives us another place to track them. We can't stop tracking them. Well we could, but their existence is valuable. For example in the case of these "missing overview pages" we included them as Write the Docs tasks (https://docs.google.com/document/d/1QNMGDt-I2hW_RWTzq9a60IzZsh6fDn80kW3N4WWG_TU/edit#) so it was helpful having issues to track them.

hamishwillee commented 2 years ago

I tend to agree with @wbamberg on this one - missing overview pages are worth tracking and keeping open because we "really do want them" (by contrast I'd be happy if we closed every single issue about a missing interface item "by default" - there are so many that they are just clutter).

How do we move from tracking these valuable things to documenting them?

sideshowbarker commented 2 years ago

How do we move from tracking these valuable things to documenting them?

For getting help with that, here’s one concrete suggestion: From the Twitter https://twitter.com/mozdevnet account, somebody could post a tweet something like this:

Know the Device Orientation API well? Want to help other developers understand it better? One way you can: Write a Device Orientation Events API overview for MDN. Along with helping other developers, that’ll resolve an issue that’s been open for 2+ years https://github.com/mdn/content/issues/2644

mdn / content

Add API overview page for Device Orientation Events #2644