docs: add comments from #1115 to faq and styleguide

docs/docs/faq.md

@@ -7,9 +7,6 @@ sidebar_position: 6
 
 This page contains a list of frequently asked questions about Task.
 
-- [Why won't my task update my shell environment?](#why-wont-my-task-update-my-shell-environment)
-- ['x' builtin command doesn't work on Windows](#x-builtin-command-doesnt-work-on-windows)
-
 ## Why won't my task update my shell environment?
 
 This is a limitation of how shells work. Task runs as a subprocess of your
@@ -30,6 +27,54 @@ my-shell-env:
 Now run `eval $(task my-shell-env)` and the variables `$FOO` and `$BAR` will be
 available in your shell.
 
+## I can't reuse my shell in a task's commands
+
+Task runs each command as a separate shell process, so something you do in one
+command won't effect any future commands. For example, this won't work:
+
+```yaml
+version: '3'
+
+tasks:
+  foo:
+    cmds:
+      - a=foo
+      - echo $a
+      # outputs ""
+```
+
+To work around this you can either use a multiline command:
+
+```yaml
+version: '3'
+
+tasks:
+  foo:
+    cmds:
+      - |
+        a=foo
+        echo $a
+      # outputs "foo"
+```
+
+Or for more complex multi-line commands it is recommended to move your code into
+a separate file and call that instead:
+
+```yaml
+version: '3'
+
+tasks:
+  foo:
+    cmds:
+      - ./foo-printer.bash
+```
+
+```bash
+#!/bin/bash
+a=foo
+echo $a
+```
+
 ## 'x' builtin command doesn't work on Windows
 
 The default shell on Windows (`cmd` and `powershell`) do not have commands like

docs/docs/styleguide.md

@@ -214,3 +214,27 @@ tasks:
 ```
 
 This is also done automatically when using included Taskfiles.
+
+## Prefer external scripts over complex multi-line commands
+
+```yaml
+# bad
+version: '3'
+
+tasks:
+  build:
+    cmds:
+      - |
+        for i in $(seq 1 10); do
+          echo $i
+          echo "some other complex logic"
+        done'
+
+# good
+version: '3'
+
+tasks:
+  build:
+    cmds:
+      - ./scripts/my_complex_script.sh
+```