           (execution/execute-step args (child-context ctx 3) failure-step))))))
 
 (defn ^{:is-alias true} alias
-  "just runs child but child is displayed with the given alias in visualization"
+  "Just runs child but child is displayed with the given alias in visualization.
+
+  Example:
+  ```clojure
+  (def pipeline-structure
+    `(; ...
+      (alias \"tests\"
+        (run
+          unit-test
+          acceptance-test)))
+  ```"
   [alias child]
   (run child))
 
 (defn with-workspace
-  "runs given steps with a clean workspace given to child step as :cwd argument"
+  "Runs given steps with a clean workspace given to child step as :cwd argument.
+  Commonly used if a build step needs some temporary directory to run, e.g. clone repositories and run build tasks.
+  The given workspace is not persistent, it only exists for the runtime of the build step and is deleted afterwards.
+  Long-living artifacts should be stored in an external artifact repository or using additional libraries like [`lambdacd-artifacts`](https://github.com/flosell/lambdacd-artifacts).
+
+  Example:
+  ```clojure
+  (defn some-step [args ctx]
+    (println \"The working directory:\" (:cwd args)))
+
+  (def pipeline-structure
+    `(; ...
+      (with-workspace
+        some-step
+        some-other-step)))
+  ```
+  "
   [& steps]
   (fn [args ctx]
     (let [home-dir (:home-dir (:config ctx))

                           :retrigger-predicate parallel-retrigger-predicate
                           :is-killed (:is-killed ctx)))

(defn ^{:display-type :parallel} in-parallel [& steps]
  (fn [args ctx]
    (post-process-container-results
      (execute-steps-in-parallel steps args ctx))))


(defn ^{:display-type :container} in-cwd [cwd & steps]
  (fn [args ctx]
    (post-process-container-results
      (execution/execute-steps steps (assoc args :cwd cwd) ctx

(ns lambdacd.steps.control-flow
  "Control-flow elements for a pipeline: steps that control the way their child-steps are being run."
  (:require [lambdacd.execution.core :as execution]
            [clojure.core.async :as async]
            [lambdacd.steps.support :as support]
