Added more explanation of apps in intro, more specifics in applicatio…

docs/developing/extending/creating-apps.rst

@@ -2,47 +2,69 @@
 Creating Applications
 #####################
 
-Starting with version 7.5, Arches moved to a new architectural pattern to support certain customization needs. This new pattern called **Arches Applications** (alternatively **Arches Apps**) should make customizations easier to develop and maintain. This architectural pattern also aligns with standard Django practices for the introduction of reusable sets of new features.
+Starting with version 7.5, Arches moved to a new architectural pattern to support certain customization needs. This new pattern called **Arches Applications** should make customizations easier to develop and maintain. This architectural pattern also aligns with standard Django practices for the introduction of reusable sets of new features.
 
 
-What's an App?
-==============
-The phrase **Arches application** (or **Arches app**) describes a Python package that provides some set of features added to the core (standard) Arches application. Arches apps can be reused in multiple Arches projects. This terminology about *applications* and *projects* purposefully aligns with the `Django definition and use of these terms <https://docs.djangoproject.com/en/4.2/ref/applications/#projects-and-applications>`_.
+What's an Application?
+======================
+The phrase **Arches Application** describes a Python package that provides some set of features added to the core (standard) Arches application. Arches application can be reused in multiple Arches projects. This terminology about *applications* and *projects* purposefully aligns with the `Django definition and use of these terms <https://docs.djangoproject.com/en/4.2/ref/applications/#projects-and-applications>`_.
 
 
 .. figure:: ../../images/dev/diagram-custom-apps-in-projects.png
     :width: 100%
     :align: center
 
-    Illustration of Arches projects integrating custom Arches Apps.
+    Illustration of Arches projects integrating custom Arches Application.
 
 
-When are Arches Apps Useful?
-============================
-Arches Apps provide a means to power special purpose features that may not be appropriate for incorporation into the core (standard) Arches application. A given Arches App can be under version control independent of core Arches. This should make it easier to update and upgrade core Arches independently of a custom Arches App (and vice versa).
+When are Arches Applications Useful?
+====================================
+Arches Arches Applications a means to power special purpose features that may not be appropriate for incorporation into the core (standard) Arches application. A given Arches App can be under version control independent of core Arches. This should make it easier to update and upgrade core Arches independently of a custom Arches Application (and vice versa).
 
-A given Arches App can also be developed and shared open source. This means that the custom features powered by an Arches App can be reused widely across the community. Because Arches App development can proceed independently of core Arches, Arches Apps can be an excellent way for community members to experiment with features beyond those listed on the official Arches software development roadmap `official Arches software development roadmap <https://www.archesproject.org/roadmap/>`_.
+A given Arches Application can also be developed and shared open source. This means that the custom features powered by an Arches Application can be reused widely across the community. Because Arches Application development can proceed independently of core Arches, Arches Applications can be an excellent way for community members to experiment with features beyond those listed on the official Arches software development roadmap `official Arches software development roadmap <https://www.archesproject.org/roadmap/>`_.
 
-`Arches for Science <https://www.archesproject.org/arches-for-science/>`_ illustrates the value of Arches apps. Arches for Science has several workflows and features (together with additional software dependencies) useful for cultural heritage conservation science. However, these features would be unnecessary for many other core Arches use cases. Keeping these conservation science features in a distinct app allows `Arches for Science software development <https://github.com/archesproject/arches-for-science/>`_ to continue at its own pace, and it reduces pressures to add highly specialized features to core Arches. Arches apps can therefore help reduce the complexity and maintenance costs of core Arches.
+`Arches for Science <https://www.archesproject.org/arches-for-science/>`_ illustrates the value of Arches Applications. Arches for Science has several workflows and features (together with additional software dependencies) useful for cultural heritage conservation science. However, these features would be unnecessary for many other core Arches use cases. Keeping these conservation science features in a distinct application allows `Arches for Science software development <https://github.com/archesproject/arches-for-science/>`_ to continue at its own pace, and it reduces pressures to add highly specialized features to core Arches. Arches Applications can therefore help reduce the complexity and maintenance costs of core Arches.
 
 
-Arches Apps Can Help Avoid Forks
---------------------------------
-Through Arches apps, desired special features can be added to an Arches instance without forking the core (standard) Arches application code. There are many advantages to avoiding forks of the core (standard) Arches application code. By avoiding forks, one can more easily take advantage of continued upgrades and security patches applied to core Arches. This makes your use of Arches easier to maintain and secure.
+Arches Applications Can Help Avoid Forks
+----------------------------------------
+Through Arches Applications, desired special features can be added to an Arches instance without forking the core (standard) Arches application code. There are many advantages to avoiding forks of the core (standard) Arches application code. By avoiding forks, one can more easily take advantage of continued upgrades and security patches applied to core Arches. This makes your use of Arches easier to maintain and secure.
 
-A given Arches App can also be developed and shared open source. This means that the custom features powered by an Arches App can be reused across the community in multiple Arches projects.
+A given Arches Application can also be developed and shared open source. This means that the custom features powered by an Arches Application can be reused across the community in multiple Arches projects.
 
 
-Getting Started with Arches Apps
-================================
-The Arches team created a simple example Arches app to illustrate how to develop and deploy custom apps. The example app called **Arches Dashboard** displays a summary count of resource instances and tiles in a given Arches project.
+Developing Arches Applications
+------------------------------
+While any given Arches Application can be reused in multiple Arches projects, one must first create an Arches project to host the Arches Application you seek to develop. You start with the following command to create a new Arches project to host your Arches Application:
 
-The **Arches Dashboard** app provides an example of how to build a custom Arches application. Experience with Django in general, and `Django app development <https://docs.djangoproject.com/en/4.2/ref/applications/#>`_ in particular, would be very useful for Arches app development. The official Django documentation provides a great starting `tutorial for learning how to create apps <https://docs.djangoproject.com/en/4.2/intro/tutorial01/#creating-the-polls-app>`_.
+.. code-block:: shell
 
+        # Create a new Arches project for your Arches Application "example_app"
+        arches-admin startproject example_app
 
 
-Installing the **Arches Dashboard** App
----------------------------------------
+Arches Applications will sometimes require specific versions of core Arches to function properly. Therefore, their maintenance and upgrade paths should be carefully considered. In addition, different Arches Applications may have different dependencies (including other Arches Applications), which can complicate future upgrades. Finally, Arches Applications may require additional testing to ensure that they are compatible with Arches Applications and with the core Arches software. In creating an Arches Application, you can specify version information and version expectations for core Arches in the ``settings.py`` file of your application.
+
+.. code-block:: python
+
+    APP_NAME = "example_app"
+    APP_VERSION = semantic_version.Version(major=1, minor=0, patch=0)
+    APP_ROOT = os.path.dirname(os.path.abspath(inspect.getfile(inspect.currentframe())))
+    MIN_ARCHES_VERSION = semantic_version.Version(major=7, minor=5, patch=0)
+    MAX_ARCHES_VERSION = semantic_version.Version(major=7, minor=6, patch=2)
+
+
+
+Getting Started with an Example Arches Application
+==================================================
+The Arches team created a simple example Arches Application to illustrate how to develop and deploy custom applications. The example application called **Arches Dashboard** displays a summary count of resource instances and tiles in a given Arches project.
+
+The **Arches Dashboard** app provides an example of how to build a custom Arches application. Experience with Django in general, and `Django app development <https://docs.djangoproject.com/en/4.2/ref/applications/#>`_ in particular, would be very useful for Arches Application development. The official Django documentation provides a great starting `tutorial for learning how to create apps <https://docs.djangoproject.com/en/4.2/intro/tutorial01/#creating-the-polls-app>`_.
+
+
+
+Installing the **Arches Dashboard** Applications
+------------------------------------------------
 You can add the dashboard to an Arches project in just a few easy steps.
 
 1. Install it from this repo (or clone this repo and pip install it locally):

docs/developing/getting-started/customization-considerations.rst

@@ -7,8 +7,19 @@ If you are leading a project or organization considering customizing Arches soft
 The practices described here will reduce costs, reduce long term maintenance and security risks, and will lead to greater impact, enhanced sustainability, and open doors for future opportunities. That said, to maximize sustainability, security, maintainability, quality and impact, it is best practice to coordinate and discuss customization plans with the wider Arches open source community. If you haven't already done so, please join the `Arches Community Forum <https://community.archesproject.org/>`_!
 
 
-More Sustainable Pathways toward Customization
-==============================================
+
+Customized Applications
+=======================
+While the Arches extensions architecture offers a great deal of flexibility (see below), there may be scenarios where you need additional flexibility. From a sustainability and maintenance perspective, this scenario has important risks that need to be understood and factored into long term resource planning and engineering.
+
+Managing long term sustainability and maintenance risks should be a core software engineering focus. As much as possible, you should ideally isolate your customized module as much as possible from the core of Arches. One way preferred way to accomplish this is to develop  **Arches Applications** (see: :ref:`Creating Applications`), which are discrete Python packages that can be integrated into one or more Arches projects. The **Arches Applications** documentation details their development as well as their sustainability advantages.
+
+Arches Applications are a powerful way to create customizations that are isolated from the core of Arches. This isolation can help to reduce the risk of future maintenance and upgrade challenges. Arches Applications can be developed and maintained independently of the core Arches software, and can be shared with the wider Arches community. This can help to ensure that your customizations are more maintainable over time. Arches Applications can also be used to create reusable components that can be shared with members of the Arches community, which can help to reduce the overall cost of development and maintenance.
+
+
+
+Customization of Simple Extensions
+==================================
 To increase the likelihood that customizations will have long term compatibility and maintainability with Arches, please use the customization patterns supported and documented by Arches. These patterns include:
 
 
@@ -27,13 +38,6 @@ To increase the likelihood that customizations will have long term compatibility
 Adherence to the extension design patterns helps to isolate your customizations from changes to the core of Arches. Following Arches extensions design patterns will also increase the likelihood that there will be relevant documentation and community help if the extensions need updates in the future. Certain customizations are easier to maintain over time. For example, an overwritten HTML template is generally simpler to upgrade than an inherited Arches Python class or an overwritten Django view. You should factor such considerations into long term resource planning.
 
 
-Customizations Beyond Extensions
-================================
-While the Arches extensions architecture offers a great deal of flexibility, there may be scenarios where you need additional flexibility. From a sustainability and maintenance perspective, this scenario has important risks that need to be understood and factored into long term resource planning and engineering.
-
-Managing long term sustainability and maintenance risks should be a core software engineering focus. As much as possible, you should ideally isolate your customized module as much as possible from the core of Arches. One way preferred way to accomplish this is to develop  **Arches Apps** (see: :ref:`Creating Applications`), which are discrete Python packages that can be integrated into one or more Arches projects. The **Arches Apps** documentation details their sustainability advantages.
-
-
 API Based Customizations
 ========================
 The Arches :ref:`API` can be used to support customizations, especially those involving integration of Arches with other information systems. Channeling all connections between Arches and other systems through the API aligns with a design practice often described as "`Loose Coupling <https://en.wikipedia.org/wiki/Loose_coupling>`_". By carefully limiting and simplifying how core Arches interfaces with external information systems, you reduce future maintenance burdens, because problems can be identified and fixed in a more focused manner.