Re: [w3c/screen-orientation] Editorial: Introduction Section (#132)

marcoscaceres requested changes on this pull request.

Looking good. You've captured the intent of the API quite nicely. Some suggestions for improvements.

> @@ -71,6 +71,51 @@
         This document is a work in progress.
       </p>
     </section>
+    <section class="informative">
+      <h2>
+        Introduction
+      </h2>
+      <p>
+        The Screen Orientation API allows web applications that would be

It might be nice to to move the last sentence first (what the API does) and then describe what affordances the API provides. Also, it might be better to frame this in the positive sense - so, not so much "negatively impacted", but more that that some applications provide a "more optional user experience" when used in particular orientations (e.g., some games in landscape). 

> +      </p>
+      <p>
+        This specification describes how the API:
+      </p>
+      <ul>
+        <li>provides the current screen orientation type and angle of a device
+        as defined in the <a>updating orientation algorithm</a>.
+        </li>
+        <li>updates the screen orientation when the viewport angle changes
+        according to the <a>screen orientation change algorithm</a>.
+        </li>
+        <li>locks the screen to a specific orientation following the <a>locking
+        orientation algorithm</a>.
+        </li>
+        <li>unlocks the locked screen to the default orientation as described
+        in the <a data-link-for="ScreenOrientation">unlock()</a> method.

Don't we have an unlock algorithm? Or are the steps to unlock explicitly part of the .unlock()?  

> +        <li>updates the screen orientation when the viewport angle changes
+        according to the <a>screen orientation change algorithm</a>.
+        </li>
+        <li>locks the screen to a specific orientation following the <a>locking
+        orientation algorithm</a>.
+        </li>
+        <li>unlocks the locked screen to the default orientation as described
+        in the <a data-link-for="ScreenOrientation">unlock()</a> method.
+        </li>
+      </ul>
+      <section>
+        <h2>
+          Goals
+        </h2>
+        <ul>
+          <li>Allow a web application to have control over screen orientation

We probably want to say something about "without being intrusive to end users". Like, a developer can't randomly change screen orientation whenever they want... only when the security conditions are met. That's the goal :) 

> +        <li>unlocks the locked screen to the default orientation as described
+        in the <a data-link-for="ScreenOrientation">unlock()</a> method.
+        </li>
+      </ul>
+      <section>
+        <h2>
+          Goals
+        </h2>
+        <ul>
+          <li>Allow a web application to have control over screen orientation
+          where needed.
+          </li>
+          <li>Support a better user experience by giving information on screen
+          orientation changes so web applications can update correspondingly.
+          </li>
+          <li>Provide a simple way for users to understand how to hold their

I think this goal needs to be phrased with a developer focus. As it reads, this would be a goal if the API gave hints to the user that the orientation was about to change - but we don't do that. We leave it to the OS. 

However, actually letting the developer know when the orientation has changed, and providing the developer with both the updated orientation and angle, so that they can make necessary adjustments to their web application is definitely a goal. 

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/screen-orientation/pull/132#pullrequestreview-191492847