diff --git a/pkg/yqlib/doc/usage/lua.md b/pkg/yqlib/doc/usage/lua.md
new file mode 100644
index 00000000..8a1df597
--- /dev/null
+++ b/pkg/yqlib/doc/usage/lua.md
@@ -0,0 +1,19 @@
+
+## Basic example
+Given a sample.yml file of:
+```yaml
+hello: world
+? look: non-string keys
+: True
+numbers: [123,456]
+
+```
+then
+```bash
+yq -o=lua '.' sample.yml
+```
+will output
+```lua
+return {["hello"]="world";[{["look"]="non-string keys";}]=true;["numbers"]={123,456,};};
+```
+
diff --git a/pkg/yqlib/lua_test.go b/pkg/yqlib/lua_test.go
index 90dc4a19..3cf28ff2 100644
--- a/pkg/yqlib/lua_test.go
+++ b/pkg/yqlib/lua_test.go
@@ -10,7 +10,6 @@ import (
 
 var luaScenarios = []formatScenario{
 	{
-		skipDoc:      true,
 		description:  "Basic example",
 		input:        "hello: world\n? look: non-string keys\n: True\nnumbers: [123,456]\n",
 		expected:     "return {[\"hello\"]=\"world\";[{[\"look\"]=\"non-string keys\";}]=true;[\"numbers\"]={123,456,};};\n",
@@ -76,11 +75,31 @@ func documentLuaScenario(t *testing.T, w *bufio.Writer, i interface{}) {
 		return
 	}
 	switch s.scenarioType {
+	case "encode":
+		documentLuaEncodeScenario(w, s)
 	default:
 		panic(fmt.Sprintf("unhandled scenario type %q", s.scenarioType))
 	}
 }
 
+func documentLuaEncodeScenario(w *bufio.Writer, s formatScenario) {
+	writeOrPanic(w, fmt.Sprintf("## %v\n", s.description))
+
+	if s.subdescription != "" {
+		writeOrPanic(w, s.subdescription)
+		writeOrPanic(w, "\n\n")
+	}
+
+	writeOrPanic(w, "Given a sample.yml file of:\n")
+	writeOrPanic(w, fmt.Sprintf("```yaml\n%v\n```\n", s.input))
+
+	writeOrPanic(w, "then\n")
+	writeOrPanic(w, "```bash\nyq -o=lua '.' sample.yml\n```\n")
+	writeOrPanic(w, "will output\n")
+
+	writeOrPanic(w, fmt.Sprintf("```lua\n%v```\n\n", mustProcessFormatScenario(s, NewYamlDecoder(ConfiguredYamlPreferences), NewLuaEncoder(ConfiguredLuaPreferences))))
+}
+
 func TestLuaScenarios(t *testing.T) {
 	for _, tt := range luaScenarios {
 		testLuaScenario(t, tt)