doc: moving the recommended variant of down command to top (openedx-unsupported#695)

jinder1s · web-flow · commit fc18637cd576 · 2021-03-16T12:39:33.000-04:00
Previously, the way the information was organized made it seem as if make dev.down would not do full docker-compse down. This hopes to fix that confusion and better organize info to recommend using make dev.down instead of make dev.down.service
diff --git a/docs/devstack_interface.rst b/docs/devstack_interface.rst
@@ -63,19 +63,24 @@ Useful Commands and Summary
 
   + ``make dev.up.without-deps.<service>`` will only bring up the <service> container
 
-- ``dev.stop.<service>``: only stops the container. This does not remove the container or the networks it has created
+- ``dev.stop``: Stops all running containers.  This does not remove the containers or the networks they had created
 
-  When to use: When you are pausing your work on this container/devstack and you want to pick back up from where you left off. Next time you use dev.up to bring up containers, you should be able to mostly pick back up from where you started.
+  When to use: When you are pausing your work on devstack and you want to pick back up from where you left off. Next time you use dev.up.<service> to bring up containers, you should be able to mostly pick back up from where you started.
 
-- ``dev.down.<service>``: stops the specified container and also removes the stopped containers as well as any networks that were created. Next time you use dev.up to bring up container, your container have reverted back to the pulled image.
+  Variation:
+  + ``make dev.stop.<service>`` will only stop the specified container
+
+- ``dev.down``: stops and removes all running containers as well as any networks that were created. Next time you use dev.up.<service> to bring up containers, your containers have reverted back to the pulled image.
 
   Note: This will not affect content of the databases.
 
-  Note: This will only bring down <service>'s container and not its dependencies.
+  When to use: use this command only if you are okay with removing any changes you might have made to your containers. You will likely want to use ``make dev.stop`` instead of ``make dev.down``.
+
+  Variation:
 
-  When to use: use this command only if you are okay with removing any changes you might have made to the container
+  + ``make dev.down.<service>`` will stop and remove only the specified container.
 
-  Variation: ``make dev.down`` will stop all your containers
+    Note: This will only bring down <service>'s container and not its dependencies.
 
 - ``dev.shell.<service>``: used to enter the shell of the specified service container.
 
