wip

Author: csviri

docs/documentation/dependent-resources.md

@@ -137,16 +137,15 @@ See the full source code [here](https://github.com/java-operator-sdk/java-operat
 
 ## Managed Dependent Resources
 
-As mentioned previously, one goal of this implementation is to make it possible to semi-declaratively create and wire
+As mentioned previously, one goal of this implementation is to make it possible to declaratively create and wire
 dependent resources. You can annotate your reconciler with
 `@Dependent` annotations that specify which `DependentResource` implementation it depends upon. JOSDK will take the
 appropriate steps to wire everything together and call your
 `DependentResource` implementations `reconcile` method before your primary resource is reconciled. This makes sense in
 most use cases where the logic associated with the primary resource is usually limited to status handling based on the
 state of the secondary resources and the resources are not dependent on each other. 
 
-Note that all dependents will be reconciled in order. If an exception happens in one or more reconciliations, the
-followup resources will be reconciled.
+See [Workflows](https://javaoperatorsdk.io/docs/dependent-resources) how/ in what order the resources are reconciled. 
 
 This behavior and automated handling is referred to as "managed" because the `DependentResource` instances 
 are managed by JOSDK.
@@ -186,15 +185,16 @@ sample [here](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/s
 
 ## Standalone Dependent Resources
 
-To use dependent resources in more complex workflows, when there are some resources needs to be created only in certain 
-conditions the standalone mode is available or the dependent resources are not independent of each other.
-For example if calling an API needs to happen if a service is already up and running 
-(think configuring a running DB instance).
+In case just some or sub-set of the resources are desired to be managed by dependent resources use standalone mode.
 In practice this means that the developer is responsible to initializing and managing and
-calling `reconcile` method. However, this gives possibility for developers to fully customize the workflow for
+calling `reconcile` method. However, this gives possibility for developers to fully customize the process for
 reconciliation. Use standalone dependent resources for cases when managed does not fit.
 
-The sample is similar to one above it just performs additional checks, and conditionally creates an `Ingress`: 
+Note that [Workflows](https://javaoperatorsdk.io/docs/dependent-resources) support also standalone mode using
+standalone resources.
+
+The sample is similar to one above it just performs additional checks, and conditionally creates an `Ingress`:
+(Note that now this condition creation is also possible with Workflows)
 
 ```java
 

docs/documentation/workflows.md

@@ -7,13 +7,55 @@ permalink: /docs/workflows
 
 ## Overview
 
+Kubernetes (k8s) does not have notion of a resource "depends on" on another k8s resource,
+in terms of in what order a set of resources should be reconciled. However, Kubernetes operators are used to manage also
+external (non 8s) resources. Typically, when an operator manages a service, where after the service is first deployed 
+some additional API calls are required to configure it. In this case the configuration step depends
+on the service and related resources, in other words the configuration needs to be reconciled after the service is 
+up and running. 
+
+The intention behind workflows is to make it easy to describe more complex, almost arbitrary scenarios in a declarative
+way. While [dependent resources](https://javaoperatorsdk.io/docs/dependent-resources) describes a logic how a single
+resources should be reconciled, workflows describes the process how a set of target resources should be reconciled in 
+a generic way. 
+
+Workflows are defined as a set of [dependent resources](https://javaoperatorsdk.io/docs/dependent-resources) (DR) 
+and dependencies between them, along with some conditions that mainly helps define optional resources and 
+pre- and post-conditions to describe expected states of a resource at a certain point in the workflow.    
+
+
 ## Elements of Workflow 
 
+- **Dependent resource** (DR) - are the resources which are reconciled.
+- **Depends on relation** - if a DR B depends on another DR A, means that B will be reconciled after A is successfully 
+  reconciled. 
+- **Reconcile precondition** - is a condition that needs to be fulfilled before the DR is reconciled. This allows also
+  to define optional resources, that for example only created if a flag in a custom resource `.spec` has some 
+  specific value.
+- **Ready postcondition** - checks if a resource could be considered "ready", typically if pods of a deployment are up
+  and running.
+- **Delete postcondition** - during the cleanup phase it can be used to check if the resources is successfully deleted,
+   so the next resource on which the target resources depends can be deleted as next step.  
+
 ## Defining Workflows
 
-## Reconcile 
+As for dependent resource there are two ways to define workflows, in managed and standalone way.
+
+### Managed
+
+
+### Standalone 
+
+
+## Reconciliation 
+
+[//]: # (todo mention parallelism)
 
 ## Cleanup
 
-## Notes and some Caveats
+## Notes
+
+- Workflows can be seen as a Directed Acyclic Graph (DAG) - or more precisely a set of DAGs - where nodes are the 
+dependent resources and edges are the dependencies.  
 
+[//]: # (ready vs precondition)