JP-3003 Clarify how to manage a local CRDS cache (#7350)

Changes
* Remove any mention of "rm" from the deprecation notice
* shorten the example path in the introduction
* update changelog
* Add information about content and size requirements
* minor word change on the deprecation instructions

(cherry picked from commit 1b8d288)

CHANGES.rst

@@ -1,3 +1,15 @@
+1.8.4 (2022-11-15)
+==================
+
+
+documentation
+-------------
+
+- Update deprecation notice with copyedit changes [#7348]
+
+- Clarify how to manage a local CRDS cache [#7350]
+
+
 1.8.3 (2022-11-11)
 ==================
 

docs/jwst/introduction.rst

@@ -82,13 +82,23 @@ two environment variables:
   - CRDS_PATH: Local folder where CRDS content will be cached.
   - CRDS_SERVER_URL: The server from which to pull reference information
 
-To setup to use JWST OPS, use the following settings:
+To setup, use the following settings:
 
 ::
 
-    export CRDS_PATH=$HOME/crds_cache/jwst_ops
+    export CRDS_PATH=$HOME/crds_cache
     export CRDS_SERVER_URL=https://jwst-crds.stsci.edu
 
+.. note::
+
+   The folder that CRDS_PATH points to should be devoid of all content, except that which CRDS will create.
+
+   The disk partition on which the cache will be stored should have sufficient
+   free space to hold at least one context's worth of references. At the moment,
+   the minimum free space should be 100GB for normal processing. If one plans on
+   downloading the full content of the CRDS database, including all contexts and
+   reference files, plan on needing a minimum of 500GB available space.
+
 .. _strun_command_line:
 
 Running From the Command Line

docs/jwst/pub_deprecation.rst

@@ -53,12 +53,35 @@ Transition Procedure
 If using the PUB server, there are two simple tasks that need to be done to
 ensure a successful transition from using the PUB server to the JWST OPS server.
 
+
 First, the folder containing the local CRDS cache, pointed to by the environment
-variable CRDS_PATH, should be cleared. Under Linux-like systems, the command is
+variable CRDS_PATH, should be cleared of all old CRDS information.
+
+If created appropriately, the folder that CRDS_CACHE points to should contain
+ONLY CRDS content. The suggested way of ensuring a new, empty cache, is to
+create a new folder. For example, to create a CRDS cache folder under a user's
+home folder, using Linux, the command is:
 
 ::
 
-   $ rm -rf $CRDS_PATH/*
+   $ mkdir $HOME/crds_cache
+
+Then set CRDS_CACHE to point to this new, empty folder:
+
+::
+
+   $ export CRDS_CACHE=$HOME/crds_cache
+
+The important point is that whatever folder is to be used to hold the CRDS cache
+should initially be empty; no other content should be present in the folder.
+
+Older CRDS cache folders are no longer needed and can be removed as the user
+sees fit.
+
+It does not matter what the folder is called, nor where it is located, as long
+as the user has access permissions to that folder. The location of the CRDS
+cache should contain sufficient space to hold the references. Current suggested
+minimum of free space is 100GB.
 
 Second, ensure that the environment variable CRDS_SERVER_URL is pointing to the
 JWST OPS server, https://jwst-crds.stsci.edu: