12 files changed, 66 insertions, 36 deletions
diff --git a/docs/html/_redirects.yaml b/docs/html/_redirects.yaml
index 5629ddd48d7e..7d7282db5fd0 100644
--- a/docs/html/_redirects.yaml
+++ b/docs/html/_redirects.yaml
@@ -1214,3 +1214,5 @@ redirects:
   to: /training/tv/tif/content-recording.html
 - from: /preview/features/direct-boot.html
   to: /training/articles/direct-boot.html
+- from: /preview/features/scoped-folder-access.html
+  to: /training/articles/scoped-directory-access.html
diff --git a/docs/html/guide/topics/data/data-storage.jd b/docs/html/guide/topics/data/data-storage.jd
index a745d00f5e39..770340be2e00 100644
--- a/docs/html/guide/topics/data/data-storage.jd
+++ b/docs/html/guide/topics/data/data-storage.jd
@@ -252,6 +252,17 @@ external storage on a computer or removes the media, and there's no security enf
 save to the external storage. All applications can read and write files placed on the external
 storage and the user can remove them.</p>
 
+<h3 id="ScopedDirAccess">Using Scoped Directory Access</h3>
+
+On Android 7.0 or later, if you need access to a specific directory on
+external storage, use scoped directory access. Scoped directory access
+simplifies how your application accesses standard external storage directories,
+such as the <code>Pictures</code> directory, and provides a simple
+permissions UI that clearly details what directory the application is
+requesting access to. For more details on scoped directory access, see
+<a href="{@docRoot}training/articles/scoped-directory-access.html">Using
+Scoped Directory Access</a>.
+
 <h3 id="ExternalPermissions">Getting access to external storage</h3>
 
 <p>In order to read or write files on the external storage, your app must acquire the
diff --git a/docs/html/images/android-7.0/scoped-directory-access-dont-ask.png b/docs/html/images/android-7.0/scoped-directory-access-dont-ask.png
new file mode 100644
index 000000000000..66829484f2ab
--- /dev/null
+++ b/docs/html/images/android-7.0/scoped-directory-access-dont-ask.png
diff --git a/docs/html/images/android-7.0/scoped-directory-access-dont-ask_2x.png b/docs/html/images/android-7.0/scoped-directory-access-dont-ask_2x.png
new file mode 100644
index 000000000000..be717f96ac0a
--- /dev/null
+++ b/docs/html/images/android-7.0/scoped-directory-access-dont-ask_2x.png
diff --git a/docs/html/images/android-7.0/scoped-directory-access-framed.png b/docs/html/images/android-7.0/scoped-directory-access-framed.png
new file mode 100644
index 000000000000..e4d619ad1d8b
--- /dev/null
+++ b/docs/html/images/android-7.0/scoped-directory-access-framed.png
diff --git a/docs/html/images/android-7.0/scoped-directory-access-framed_2x.png b/docs/html/images/android-7.0/scoped-directory-access-framed_2x.png
new file mode 100644
index 000000000000..fe17bce12b0c
--- /dev/null
+++ b/docs/html/images/android-7.0/scoped-directory-access-framed_2x.png
diff --git a/docs/html/preview/images/scoped-folder-access-dont-ask.png b/docs/html/preview/images/scoped-folder-access-dont-ask.png
deleted file mode 100644
index 5c505d956f5e..000000000000
--- a/docs/html/preview/images/scoped-folder-access-dont-ask.png
+++ /dev/null
diff --git a/docs/html/preview/images/scoped-folder-access-dont-ask_2x.png b/docs/html/preview/images/scoped-folder-access-dont-ask_2x.png
deleted file mode 100644
index 612b69f8926f..000000000000
--- a/docs/html/preview/images/scoped-folder-access-dont-ask_2x.png
+++ /dev/null
diff --git a/docs/html/preview/images/scoped-folder-access-framed.png b/docs/html/preview/images/scoped-folder-access-framed.png
deleted file mode 100644
index 0169e4196aff..000000000000
--- a/docs/html/preview/images/scoped-folder-access-framed.png
+++ /dev/null
diff --git a/docs/html/preview/images/scoped-folder-access-framed_2x.png b/docs/html/preview/images/scoped-folder-access-framed_2x.png
deleted file mode 100644
index fd59ef17d94c..000000000000
--- a/docs/html/preview/images/scoped-folder-access-framed_2x.png
+++ /dev/null
diff --git a/docs/html/training/_book.yaml b/docs/html/training/_book.yaml
index ccc4a7f9d79e..23d9c9e20ea1 100644
--- a/docs/html/training/_book.yaml
+++ b/docs/html/training/_book.yaml
@@ -1397,6 +1397,11 @@ toc:
     path_attributes:
     - name: description
       value: How use device encrypted storage during Direct Boot mode.
+  - title: Using Scoped Directory Access
+    path: /training/articles/scoped-directory-access.html
+    path_attributes:
+    - name: description
+      value: How to use scoped directory access to request access to external storage directories.
 
 - title: Best Practices for Permissions & Identifiers
   path: /training/best-permissions-ids.html
diff --git a/docs/html/preview/features/scoped-folder-access.jd b/docs/html/training/articles/scoped-directory-access.jd
index 06dd6652677d..1e0bf39fc594 100644
--- a/docs/html/preview/features/scoped-folder-access.jd
+++ b/docs/html/training/articles/scoped-directory-access.jd
@@ -1,11 +1,10 @@
-page.title=Scoped Directory Access
-page.keywords=preview,sdk,scoped directory access
-page.tags=androidn
+page.title=Using Scoped Directory Access
+page.keywords=scoped directory access
 
 @jd:body
 
-<div id="qv-wrapper">
-<div id="qv">
+<div id="tb-wrapper">
+<div id="tb">
   <h2>In this document</h2>
   <ol>
     <li><a href="#accessing">Accessing an External Storage Directory</a></li>
@@ -32,29 +31,37 @@ via a system UI, which is unnecessary if your app always accesses the same
 external directory.</li>
 </ul>
 
-<p>Android N provides a new simplified API to access
-common external storage directories. </p>
+<p>Android 7.0 provides a simplified API to access common external storage
+directories.</p>
 
 <h2 id="accessing">Accessing an External Storage Directory</h2>
 
-<p>Use the <code>StorageManager</code> class to get the appropriate
-<code>StorageVolume</code> instance. Then, create an intent by calling the
-<code>StorageVolume.createAccessIntent()</code> method of that instance.
+<p>Use the {@link android.os.storage.StorageManager} class to get the
+appropriate {@link android.os.storage.StorageVolume} instance. Then, create
+an intent by calling the
+{@link android.os.storage.StorageVolume#createAccessIntent
+StorageVolume.createAccessIntent()} method of that instance.
 Use this intent to access external storage directories. To get a list of
-all available volumes, including removable media volumes, use
-<code>StorageManager.getVolumesList()</code>.</p>
+all available volumes, including removable media
+volumes, use {@link android.os.storage.StorageManager#getStorageVolumes
+StorageManager.getStorageVolumes()}.</p>
 
 <p>If you have information about a specific file, use
-<code>StorageManager.getStorageVolume(File)</code> to get the
-<code>StorageVolume</code> that contains the file. Call
-<code>createAccessIntent()</code> on this <code>StorageVolume</code> to access
+{@link android.os.storage.StorageManager#getStorageVolume
+StorageManager.getStorageVolume(File)} to get the
+{@link android.os.storage.StorageVolume} that contains the file. Call
+{@link android.os.storage.StorageVolume#createAccessIntent
+createAccessIntent()} on this
+{@link android.os.storage.StorageVolume} to access
 the external storage directory for the file.</p>
 
 <p>
 On secondary volumes, such as external SD cards, pass in null when calling
-<code>StorageVolume.createAccessIntent()</code> to request access to the entire
+{@link android.os.storage.StorageVolume#createAccessIntent
+createAccessIntent()} to request access to the entire
 volume, instead of a specific directory.
-<code>StorageVolume.createAccessIntent()</code> returns null if you pass in
+{@link android.os.storage.StorageVolume#createAccessIntent
+createAccessIntent()} returns null if you pass in
 null to the primary volume, or if you pass in an invalid directory name.
 </p>
 
@@ -63,7 +70,7 @@ null to the primary volume, or if you pass in an invalid directory name.
 
 <pre>
 StorageManager sm = (StorageManager)getSystemService(Context.STORAGE_SERVICE);
-StorageVolume volume = sm.getPrimaryVolume();
+StorageVolume volume = sm.getPrimaryStorageVolume();
 Intent intent = volume.createAccessIntent(Environment.DIRECTORY_PICTURES);
 startActivityForResult(intent, request_code);
 </pre>
@@ -71,25 +78,27 @@ startActivityForResult(intent, request_code);
 <p>The system attempts to grant access to the external directory, and if
 necessary confirms access with the user using a simplified UI:</p>
 
-<img src="{@docRoot}preview/images/scoped-folder-access-framed.png"
-srcset="{@docRoot}preview/images/scoped-folder-access-framed.png 1x,
-{@docRoot}preview/images/scoped-folder-access-framed_2x.png 2x" />
+<img src="{@docRoot}images/android-7.0/scoped-directory-access-framed.png"
+srcset="{@docRoot}images/android-7.0/scoped-directory-access-framed.png 1x,
+{@docRoot}images/android-7.0/scoped-directory-access-framed_2x.png 2x" />
 <p class="img-caption"><strong>Figure 1.</strong> An application requesting
 access to the Pictures directory.</p>
 
 <p>If the user grants access, the system calls your
-<code>onActivityResult()</code> override with a result code of
-<code>Activity.RESULT_OK</code>, and intent data that contains the URI. Use
+{@link android.app.Activity#onActivityResult onActivityResult()} override
+with a result code of {@link android.app.Activity#RESULT_OK
+RESULT_OK}, and intent data that contains the URI. Use
 the provided URI to access directory information, similar to using URIs
 returned by the
 <a href="{@docRoot}guide/topics/providers/document-provider.html">Storage
 Access Framework</a>.</p>
 
 <p>If the user doesn't grant access, the system calls your
-<code>onActivityResult()</code> override with a result code of
-<code>Activity.RESULT_CANCELED</code>, and null intent data.</p>
+{@link android.app.Activity#onActivityResult onActivityResult()} override
+with a result code of {@link android.app.Activity#RESULT_CANCELED
+RESULT_CANCELED}, and null intent data.</p>
 
-<p class="note"><b>Note</b>: Getting access to a specific external directory
+<p>Getting access to a specific external directory
 also gains access to subdirectories within that directory.</p>
 
 <h2 id="removable">Accessing a Directory on Removable Media</h2>
@@ -112,9 +121,9 @@ first add a {@link android.content.BroadcastReceiver} that listens for the
 
 <p>When the user mounts removable media, like an SD card, the system sends a
 {@link android.os.Environment#MEDIA_MOUNTED} notification. This notification
-provides a <code>StorageVolume</code> object in the intent data that you can
-use to access directories on the removable media. The following example
-accesses the <code>Pictures</code> directory on removable media:</p>
+provides a {@link android.os.storage.StorageVolume} object in the intent data
+that you can use to access directories on the removable media. The following
+example accesses the <code>Pictures</code> directory on removable media:</p>
 
 <pre>
 // BroadcastReceiver has already cached the MEDIA_MOUNTED
@@ -129,19 +138,22 @@ startActivityForResult(intent, request_code);
 
 <p>Where possible, persist the external directory access URI so you don't have
 to repeatedly ask the user for access. Once the user has granted access, call
-<code>getContentResolver().takePersistableUriPermssion()</code> with the
-directory access URI. The system will persist the URI and subsequent access
-requests will return <code>RESULT_OK</code> and not show confirmation UI to the
-user.</p>
+{@link android.content.Context#getContentResolver getContentResolver()} and
+with the returned {@link android.content.ContentResolver} call
+{@link android.content.ContentResolver#takePersistableUriPermission
+takePersistableUriPermission()} with the directory access URI. The system will
+persist the URI and subsequent access requests will return
+{@link android.app.Activity#RESULT_OK RESULT_OK} and not show confirmation
+UI to the user.</p>
 
 <p>If the user denies access to an external directory, do not immediately
 request access again. Repeatedly insisting on access results in a poor user
 experience. If a request is denied by the user, and the app requests access
 again, the UI displays a <b>Don't ask again</b> checkbox:</p>
 
-<img src="{@docRoot}preview/images/scoped-folder-access-dont-ask.png"
-srcset="{@docRoot}preview/images/scoped-folder-access-dont-ask.png 1x,
-{@docRoot}preview/images/scoped-folder-access-dont-ask_2x.png 2x" />
+<img src="{@docRoot}images/android-7.0/scoped-directory-access-dont-ask.png"
+srcset="{@docRoot}images/android-7.0/scoped-directory-access-dont-ask.png 1x,
+{@docRoot}images/android-7.0/scoped-directory-access-dont-ask_2x.png 2x" />
 <p class="img-caption"><strong>Figure 1.</strong> An application making a
 second request for access to removable media.</p>