docs: imrpve faq page

Author: SerhiiCho

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project Overview
 
-VitePress documentation site for Textwire.
+VitePress documentation site for Textwire templating engine for Go programming language.
 
 ## Directory Structure
 
@@ -16,4 +16,8 @@ VitePress documentation site for Textwire.
 ## Development
 
 - No tests needed
-- Build: `npm run build`
+- Build: `npm run build` (only if you really need it because it's a slow process)
+
+## Important
+
+If you write inline code examples with `{{` and `}}` braces that Textwire uses, wrap them in <code v-pre></code> HTML tags instead. Intead of `{{ x = 5}}` Textwire example, you should write <code v-pre>{{ x = 5 }}</code>. It's because if you write it with backtics, Vue will execute them since `{{ }}` braces are also used in Vue.js.

docs/versions/v3/faq.md

@@ -1,56 +1,58 @@
 ---
 title: FAQ - v3
-description: Find answers to common questions and helpful tips in our FAQ section. Get quick solutions to common issues and learn more about our services
+description: Find answers to common questions about Textwire, a templating engine for Go
 ---
 
-# Frequently Asked Questions (FAQ)
+# Frequently Asked Questions
 
-Welcome to our FAQ page, where we address the most common questions and concerns about using Textwire. Whether you’re new to **Textwire** or a seasoned user, the FAQ is designed to provide quick and helpful answers to your most pressing queries.
+Find answers to common questions about Textwire. If you don't find what you're looking for, feel free to [open an issue on GitHub](https://github.com/textwire/textwire.github.io/issues/new).
 
-Here, you’ll find explanations, solutions to common problems, and best practices to make the most of your experience. If you don’t find the answer you’re looking for, feel free to reach out to us by creating an [issue on GitHub](https://github.com/textwire/textwire.github.io/issues/new) and we’ll be happy to help and update the FAQ with your question to help others.
+## What is Textwire?
 
-## What Exactly is Textwire?
+Textwire is a templating engine for Go. You implement your business logic in Go and pass data to Textwire templates to generate dynamic content. It is designed to be fast, efficient, and easy to use.
 
-Textwire is a templating engine for Go programming language. You do all of your business logic in Go and pass data to Textwire templates to generate dynamic content. It is designed to be fast, efficient, and easy to use.
-
-- ✅ We're committed to performance optimization and better error handling
-- ✅ Our priority is keeping the language core solid and reliable
-- ❌ We steer clear of shiny features that would only add bloat
+- Committed to performance optimization and solid error handling
+- Focused on keeping the language core reliable
+- Avoids features that add unnecessary complexity
 
 ## How Does Textwire Parse Files?
 
-Textwire has its own unique chain of turning your text files into final output. We do it in 4 steps:
+Textwire processes templates in four stages:
 
-1. **Tokenizing** your Textwire template into tokens.
-2. **Parsing** turns tokens into [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) nodes.
-3. **Linking** connects related AST nodes to each other.
-4. **Evaluating** turns connected AST nodes into final text output.
+1. **Tokenizing** - Breaks the template into tokens
+2. **Parsing** - Converts tokens into [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) nodes
+3. **Linking** - Connects related AST nodes
+4. **Evaluating** - Generates the final text output
 
-All non-Textwire-specific parts of the text file are treated as plain text and are not parsed as HTML, XML, or any other format. They remain unmodified in the final output, including whitespace preservation. Only Textwire-specific parts are processed:
+Non-Textwire content is treated as plain text and passes through unchanged, including whitespace. Only Textwire-specific syntax is processed:
 
 ```textwire
-<h1>Textwire seems cool</h1>
+<h1>Welcome</h1>
 {{ "Hello, World!".upper() }}
-<p>I would use it in production<p>
+<p>Ready for production</p>
 ```
 
-In the example above, only <code v-pre>{{ "Hello, World!".upper() }}</code> part will be evaluated. That's why Textwire is fast, as it only parses the parts that are necessary and leaves the rest as is.
+In the example above, only <code v-pre>{{ "Hello, World!".upper() }}</code> is evaluated. This selective parsing is what makes Textwire fast compared to other templating engines.
 
-## Prevent Visitors from Seeing Error
+## Why Hide Error Output from Visitors?
 
-When an error occurs in your function, the output may be incorrect or misleading. Displaying faulty output to users can result in confusing information, broken layouts, or unintentional exposure of sensitive data.
+When a function error occurs, the output may be incorrect or misleading. Displaying faulty output to users can result in:
 
-Hiding incorrect output when errors occur ensures that visitors only see validated, correct content, maintaining both data integrity and user trust while preventing potential security risks.
+- Confusing information or broken layouts
+- Unintentional exposure of sensitive data
+- Security vulnerabilities
 
-## The Difference Between Directives and Statements
+For example, a function might return partial or incorrect data due to a logic error or invalid input. Displaying this to visitors negatively impacts user experience and may reveal internal system details.
 
-Directives and statements are the core of Textwire language. They are used to define the structure and behavior of your text files. However, there are some key differences between them:
+By hiding incorrect output when errors occur, you ensure visitors only see validated, correct content. This maintains data integrity, user trust, and prevents potential security risks.
 
-- All directives are statements, but not all statements are directives
-- Directives start with the `@` symbol, while statements are a general term for parts of code that perform an action and do not return a value
+## Directives vs Statements
 
-:::info Read More
-You can read about statements in the [Statements](/v3/language-elements/directives) section of the documentation.
-:::
+Directives and statements are fundamental elements of the Textwire language. Both define the structure and behavior of your templates, but they differ in form:
 
-For example, `{{ x = 5 }}` is a statement that assigns the value `5` to the variable `x`. On the other hand, `@use('~main')` is a directive and a statement at the same time, as it includes the layout `main` in the current file and doesn't return a value.
+- **Directives** start with the `@` symbol (e.g., `@use`, `@if`, `@for`)
+- **Statements** are expressions that perform an action but don't return a value (e.g., <code v-pre>{{ x = 5 }}</code>)
+
+:::info Learn More
+See the [Directives](/v3/language-elements/directives) section for a complete reference.
+:::