rename for consistency (#2216)

* fix

* rename files

* rename titles

* rename

* pluralize

* fix

* sub-process

* sub-process

* sub-process

* renames

* rename

---------

Co-authored-by: burnettk <[email protected]>

docs/explanation/dev/index.md

@@ -3,9 +3,9 @@
 ```{toctree}
 :caption: Technical Docs
 :maxdepth: 1
-overview
-setup
-backend
+technical_overview
+developer_setup
+backend_api
 frontend
 connector_proxy
 how_to_build_a_connector

docs/explanation/dev/overview.md → docs/explanation/dev/technical_overview.md

@@ -24,7 +24,7 @@ C[Connector Proxy]
 ```
 
 SpiffArena is a system that allows users to build and execute BPMN diagrams.
-It is composed of three applications, [spiffworkflow-frontend](frontend), [spiffworkflow-backend](backend), and, optionally, a [connector proxy](connector_proxy).
+It is composed of three applications, [spiffworkflow-frontend](frontend), [spiffworkflow-backend](backend_api), and, optionally, a [connector proxy](connector_proxy).
 
 ## Source code layout
 

docs/explanation/index.md

@@ -6,7 +6,7 @@ In this section, you will find explanations of key concepts and processes in Spi
 :maxdepth: 1
 :titlesonly:
 articles
-learn_basics
+understanding_the_terminology
 dev/index
 process_error_handling
 ```

docs/how_to_guides/building_diagrams/bpmn.md → docs/how_to_guides/building_diagrams/create_a_bpmn_diagram.md

@@ -1,12 +1,12 @@
-# How to Create a BPMN Diagram
+# Create a BPMN Diagram
 
 Starting to model a business process can indeed be a challenging task, especially when multiple departments and users are involved.
 Here are some helpful tips to guide you through the process and create effective process models:
 
 **Understand BPMN Symbols:**
 Begin by thoroughly understanding the meaning and usage of each BPMN symbol.
 This will ensure that you use the symbols correctly to represent the various elements of your business process.
-Refer to the [Learn Basics](/explanation/learn_basics) section to learn more about each symbol.
+Refer to the [Learn Basics](/explanation/understanding_the_terminology) section to learn more about each symbol.
 
 Grouping them together can create a mind map that's easy to remember.
 
@@ -33,7 +33,7 @@ For example, "Approve Request," "Review Documents," "Send Invoice," etc.
 
 **Start with High-Level Overview:**
 Beginning with a high-level overview of the process provides a clear understanding of the overall flow and allows for the identification of major process components before delving into finer details.
-By breaking the process down into smaller subprocesses or call activities with different levels of detail, the model becomes more manageable and easier to comprehend.
+By breaking the process down into smaller sub-processes or call activities with different levels of detail, the model becomes more manageable and easier to comprehend.
 This approach enables the use of placeholders where you are unclear about what the process looks like, allowing for flexibility in filling in missing information as it becomes available.
 It also facilitates the focus on specific sections, preventing feeling overwhelmed by the complexity of the entire process.
 This systematic approach to process modeling ensures that essential aspects are adequately captured while providing room for further refinement.

docs/how_to_guides/building_diagrams/displaying_content.md → docs/how_to_guides/building_diagrams/display_content.md

@@ -1,4 +1,4 @@
-# Displaying Content
+# Display Content
 
 The SpiffArena platform offers powerful features for displaying content within your BPMN processes.
 Follow the steps below to effectively display content in your processes.

docs/how_to_guides/building_diagrams/index.md

@@ -2,10 +2,10 @@
 
 ```{toctree}
 :maxdepth: 1
-bpmn
-user_tasks_and_forms
-displaying_content
-builtin_examples
-executable_non_executable
+create_a_bpmn_diagram
+use_user_tasks_and_forms
+display_content
+overview_of_builtin_examples
+use_executable_and_nonexecutable_tasks
 bpmn_unit_tests
 ```

docs/how_to_guides/building_diagrams/builtin_examples.md → docs/how_to_guides/building_diagrams/overview_of_builtin_examples.md

@@ -1,4 +1,4 @@
-# Built-in Examples Overview
+# Overview of Built-in Examples
 
 When logging into the dashboard, it is crucial to familiarize yourself with the functions it offers and how the underlying engine operates.
 In the demo website, we will explore two examples: the Minimal Example and the Essential Example, to provide a clear understanding of the process.

docs/how_to_guides/building_diagrams/executable_non_executable.md → docs/how_to_guides/building_diagrams/use_executable_and_nonexecutable_tasks.md

@@ -1,4 +1,4 @@
-# Executable and Non-Executable Tasks
+# Use Executable and Non-Executable Tasks
 
 In SpiffWorkflow, a process model can be either **Executable** or **Non-Executable**, and the designation impacts how the workflow behaves:
 - **Executable Process**: Configured for automation and execution by the workflow engine. All tasks within the process are actionable and designed to run dynamically.

docs/how_to_guides/building_diagrams/user_tasks_and_forms.md → docs/how_to_guides/building_diagrams/use_user_tasks_and_forms.md

@@ -1,4 +1,4 @@
-# User Tasks and Forms
+# Use User Tasks and Forms
 User Tasks are a key feature in BPMN (Business Process Model and Notation) workflows where human interaction is required to complete a process. In SpiffWorkflow, User Tasks are closely integrated with Forms, which are used to collect input or display information to users during process execution.
 
 Some key features of user tasks are:

docs/how_to_guides/deployment/okta_config.md → docs/how_to_guides/deployment/configure_okta_as_an_openid_provider.md

@@ -1,4 +1,4 @@
-# Configuring Okta as an OpenID Provider
+# Configure Okta as an OpenID Provider
 This guide provides steps to configure Okta as an OpenID Provider (alternative to Keycloak) for SpiffWorkflow. 
 
 The setup involves creating an OpenID Connect (OIDC) application, configuring environment variables, and ensuring group information is passed through correctly.  

docs/how_to_guides/deployment/secrets.md → docs/how_to_guides/deployment/configure_secrets.md

@@ -1,4 +1,4 @@
-# How to Configure Secrets in SpiffArena
+# Configure Secrets
 
 ## Introduction
 
@@ -18,36 +18,40 @@ Secrets are only used in service tasks.
 - **SpiffArena Admin**: Can add or configure secrets.
 - **External Service Admin**: For example, an admin in Bamboo HR can provide the API key that a SpiffArena admin would then configure as a secret.
 - **Diagram Author**: Can reference secrets in service tasks but cannot see the actual secret values.
+
 ---
 
 ## How to Configure Secrets
 
 ### Adding a New Secret
 
 1. **Navigate to the Configuration Section**: Go to the configuration section from the top panel and click on "Add a secret." Ensure you have admin access to SpiffArena.
-![Configuration Section](/images/Secrets_step_1.png)
+   ![Configuration Section](/images/Secrets_step_1.png)
 
 2. **Add New Secret**: Create a new secret by entering a key and its corresponding value. Once saved, the value will be encrypted.
-![Secrets Section](/images/Secrets_step_2.png)
+   ![Secrets Section](/images/Secrets_step_2.png)
 
 ### Using Secrets in Service Tasks
 
-1. **Open the BPMN Diagram**: Open the diagram where you want to configure the service task.
+1.  **Open the BPMN Diagram**: Open the diagram where you want to configure the service task.
+
+2.  **Configure Service Task**: Click on the service task you want to configure and in the service properties panel, search for the Operator ID that you want to add a secret for and mention the response variable to capture the result of the request.
 
-2. **Configure Service Task**: Click on the service task you want to configure and in the service properties panel, search for the Operator ID that you want to add a secret for and mention the response variable to capture the result of the request.
+3.  **Add Secret Reference**: In the parameters, you can reference the secret using the following format:
 
-3. **Add Secret Reference**: In the parameters, you can reference the secret using the following format:
+        ```xml
+        spiffworkflow:parameter id="headers" type="any" value="{ "Authorization": "Bearer SPIFF_SECRET:github_oauth" }"
+        ```
 
-    ```xml
-    spiffworkflow:parameter id="headers" type="any" value="{ "Authorization": "Bearer SPIFF_SECRET:github_oauth" }"
-    ```
+        Here, `SPIFF_SECRET:github_oauth` will be replaced by the actual, unencrypted value from the database when the service task runs.
+
+    ![Secrets Configuration](/images/Secrets_configure_2.png)
 
-    Here, `SPIFF_SECRET:github_oauth` will be replaced by the actual, unencrypted value from the database when the service task runs.
-![Secrets Configuration](/images/Secrets_configure_2.png)
 ---
 
 Configuring secrets in SpiffArena provides a secure way to handle sensitive information in your BPMN diagrams.
 It allows you to make your processes public without exposing critical data, thereby enhancing both transparency and security.
 
 ```{tags} how_to_guide
+
 ```

docs/how_to_guides/deployment/deployment.md → docs/how_to_guides/deployment/deploy.md

@@ -1,4 +1,4 @@
-# Deployment
+# Deploy
 
 The minimal deployment is to mimic the docker-compose.yml file at the root of spiff-arena.
 Steps for a more hardened production setup after that baseline include:
@@ -28,4 +28,5 @@ API, Celery Worker, Connector Proxy, and Frontend can run any number of replicas
 The Background container is like a cron container, so it should run only one replica.
 
 ```{tags} how_to_guide
+
 ```

docs/how_to_guides/deployment/deploy_aws_lambda.md → docs/how_to_guides/deployment/deploy_a_connector_proxy_as_an_aws_lambda_function.md

@@ -1,4 +1,4 @@
-# Deploying a Connector Proxy as an AWS Lambda Function
+# Deploy a Connector Proxy as an AWS Lambda Function
 
 This guide shows you how to deploy the demo `Connector Proxy` as an `AWS Lambda Function` and integrate it with [SpiffArena](https://www.spiffworkflow.org/pages/spiffarena/).
 We will use the [Getting Started Guide](https://www.spiffworkflow.org/posts/articles/get_started/) as the basis for integration, but the steps should easily map to any custom installation.
@@ -64,7 +64,7 @@ Click your function URL again to see a greeting from our deployed Connector Prox
 ## Integrating With SpiffArena
 
 Congratulations, your Connector Proxy has been deployed as a Lambda function.
-For information on configuring SpiffArena to use the new Connector Proxy URL, please see [Configure a Connector Proxy](configure_connector_proxy).
+For information on configuring SpiffArena to use the new Connector Proxy URL, please see [Configure a Connector Proxy](configure_a_connector_proxy).
 
 ```{tags} how_to_guide, devops
 ```

docs/how_to_guides/deployment/index.md

@@ -2,13 +2,13 @@
 
 ```{toctree}
 :maxdepth: 1
-deployment.md
-secrets
-admin_and_permissions
-okta_config
-path_based_routing.md
-redis_celery_broker.md
-deploy_aws_lambda.md
-configure_connector_proxy
-process_model_management.md
+deploy
+configure_secrets
+manage_permissions
+configure_okta_as_an_openid_provider
+use_pathbased_routing
+work_with_redis_celery_broker
+deploy_a_connector_proxy_as_an_aws_lambda_function
+configure_a_connector_proxy
+manage_process_models
 ```

docs/how_to_guides/deployment/admin_and_permissions.md → docs/how_to_guides/deployment/manage_permissions.md

@@ -1,4 +1,4 @@
-# Admin and Permissions
+# Manage Permissions
 
 Permissions can be defined and managed at different levels such as process groups, individual processes, or users.
 
@@ -133,7 +133,7 @@ The Process Model view should now include all uploaded files.
 ### Step 4: Understand the Process Models
 
 [Read more about DMN tables and how they work here.
-](/reference/bpmn/dmn)
+](/reference/bpmn/decision_tables)
 
 #### Users to Groups
 
@@ -158,7 +158,7 @@ Now that the groups have been identified, their permissions can be set by adding
   For instance, ["read", "start"] indicates that the user can perform both reading and starting actions.
   Alternatively, [All] can be employed to grant unrestricted access.
 - The hit policy is set to "Collect" which means that all conditions that are true will be applied.
-  [Read more about DMN tables and hit policies here.](/reference/bpmn/dmn)
+  [Read more about DMN tables and hit policies here.](/reference/bpmn/decision_tables)
 - The permission URL can be configured to define the user's access privileges.
   Our objective is to streamline the process by minimizing the necessity of being familiar with the complete set of permission URLs.
   In most instances, utilizing BASIC and ELEVATED permissions, as well as PM/PG, should be sufficient.

docs/how_to_guides/deployment/process_model_management.md → docs/how_to_guides/deployment/manage_process_models.md

@@ -1,4 +1,4 @@
-# Process Model Management
+# Manage Process Models
 
 Managing your process models is similar to managing your source code.
 As such, it is recommended to store these models in a version control system like Git so that you can track changes and collaborate with others.

docs/how_to_guides/deployment/path_based_routing.md → docs/how_to_guides/deployment/use_pathbased_routing.md

@@ -1,4 +1,4 @@
-# Path-based Routing
+# Use Path-based Routing
 
 If you are using the frontend, the frontend and backend need to share cookies.
 The backend, in particular, sets a cookie, and the frontend needs to read it.

docs/how_to_guides/deployment/redis_celery_broker.md → docs/how_to_guides/deployment/work_with_redis_celery_broker.md

@@ -1,4 +1,4 @@
-# Redis Celery Broker
+# Work with Redis Celery Broker
 
 SpiffWorkflow can be configured to use Celery for efficient processing.
 Redis can be used as both a broker and backend for Celery.
@@ -41,4 +41,5 @@ echo 'keys celery-task-meta-\*' | redis-cli | sed 's/^/get /' | redis-cli
 ```
 
 ```{tags} how_to_guide, dev_docs
+
 ```

docs/how_to_guides/index.md

@@ -7,8 +7,8 @@
 :caption: How-to Guides
 building_diagrams/index
 manage_processes
-welcome_messages
-custom_process_metadata
-running_server_locally
+manage_welcome_messages
+use_custom_process_metadata
+troubleshoot_locally
 deployment/index
 ```

docs/how_to_guides/manage_processes.md

@@ -38,7 +38,7 @@ The process instance remains highlighted in yellow.
 |                            ✅ Success                             |
 | :---------------------------------------------------------------: |
 | Confirm that the status has changed from ‘waiting’ to ‘suspended’ |
-|                ![suspended](/images/suspended.png)                 |
+|                ![suspended](/images/suspended.png)                |
 
 ## Resume a Process Instance
 
@@ -62,7 +62,7 @@ Resuming a process is essential for ensuring that the process can continue its e
 |                                ✅ Success                                 |
 | :-----------------------------------------------------------------------: |
 | Confirm that the status has changed from ‘suspended’ to an active status. |
-|                      ![waiting](/images/waiting.png)                       |
+|                      ![waiting](/images/waiting.png)                      |
 
 ## Terminate a Process Instance
 
@@ -91,7 +91,7 @@ There are various reasons for terminating a process instance such as the instanc
 |                              ✅ Success                              |
 | :------------------------------------------------------------------: |
 | Confirm that the status has changed from ‘suspended’ to 'terminated' |
-|                  ![suspend](/images/terminated.png)                   |
+|                  ![suspend](/images/terminated.png)                  |
 
 ## Reset a Process Instance
 
@@ -184,14 +184,15 @@ In the case of the example, once you resume the instance and complete Manual Tas
 
 Migration is not possible when the following activities are active (started/ready/waiting):
 
-- Call activity/Subprocess - The task itself cannot be changed once it is active.
-  Tasks inside the call activity or subprocess can be updated if they have not been reached.
+- Call activity/Sub-process - The task itself cannot be changed once it is active.
+  Tasks inside the call activity or sub-process can be updated if they have not been reached.
   Tasks that directly follow one of these activities are special, and you cannot migrate an instance if you add or remove one of these.
 
 - Multi Instance tasks
 - Loop tasks
 - Signal boundary event - add/remove signals
 - Looping back through a part of a process which has already completed once
+
 #### Forms
 
 Forms are not serialized as part of the process model specification, and therefore are not considered during migration.
@@ -222,4 +223,5 @@ General path params:
 - **process_instance_id**: the id of the process instance to run on.
 
 ```{tags} how_to_guide
+
 ```

docs/how_to_guides/welcome_messages.md → docs/how_to_guides/manage_welcome_messages.md

@@ -1,4 +1,4 @@
-# Welcome Messages
+# Manage Welcome Messages
 
 ## Introduction
 

docs/how_to_guides/running_server_locally.md → docs/how_to_guides/troubleshoot_locally.md

@@ -1,4 +1,4 @@
-# Troubleshooting Locally
+# Troubleshoot Locally
 
 When setting up the SpiffWorkflow backend project locally, you might encounter issues related to the `sample-process-models` directory.
 This documentation aims to address those concerns.

docs/how_to_guides/custom_process_metadata.md → docs/how_to_guides/use_custom_process_metadata.md

@@ -1,4 +1,4 @@
-# Custom Process Metadata
+# Use Custom Process Metadata
 
 This guide will walk you through the steps to create a process model that generates custom metadata using a metadata extraction path and how to query that metadata using process instance filtering.
 

docs/reference/bpmn/conditional_events.md

@@ -1,4 +1,4 @@
-# Conditional Event
+# Conditional Events
 
 A Conditional Event is a type of event that activates based on the evaluation of a condition, typically expressed as a Boolean expression (true or false).
 Conditional Events depend on the state or value of process variables that are part of the process context.

docs/reference/bpmn/data_objects.md

@@ -75,7 +75,7 @@ This documentation outlines the process of creating and managing sensitive data
 
 #### 4. Implementing Access Controls
 
-- **Permission Rules**: Establish permission rules, using a Decision Model and Notation (DMN) table or another mechanism as described under [Admin and Permissions](/how_to_guides/deployment/admin_and_permissions).
+- **Permission Rules**: Establish permission rules, using a Decision Model and Notation (DMN) table or another mechanism as described under [Admin and Permissions](/how_to_guides/deployment/manage_permissions).
   This step involves specifying who can access the sensitive data.
 - **Access Restrictions**: Define the access level (e.g., read, write, deny) for different user groups or roles.
   For instance, you might restrict read access to certain groups while denying it to others.