website tweaks

website/docs/10-faq.md

@@ -0,0 +1,39 @@
+# Frequently Asked Questions
+
+## What is the origin of the name "Flyde"?
+
+"Flyde" means "flow" in Danish. Flow is a central concept in Flyde. And while we have no direct connection to Denmark, we appreciate the simplicity and functionality that Danish design often represents.
+
+## Is Flyde "no-code"?
+
+No. Flyde is a visual **programming** language, which means that it is a tool for creating software. While it may lower the barrier to entry for programming, just like assembly did to punch cards, and just like JavaScript did to C, it is still a programming language. If it has to be classified, it would be more accurate to call it a "low-code" tool, but even that is not a definition we're comfortable with.
+
+## What about performance?
+
+At the project's current stage, running a program using Flyde's runtime will be slower than running the same program written in TypeScript/JavaScript. The primary focus is on making the development experience as smooth as possible. We believe that the benefits of visual programming, such as increased readability and maintainability, will outweigh the performance cost for most use cases.
+
+Moreover, once the project matures, many optimizations can be made to the runtime to improve performance. For example, we can compile the visual flow to a more efficient representation to avoid needing to interpret the flow at runtime. The runtime could be rewritten in a lower-level language, or even compiled to WebAssembly for better performance. These are all possibilities for the future.
+
+## How Flyde relates to flow-based programming (FBP)?
+
+Flyde is a visual programming language that is heavily inspired by flow-based programming (FBP). We came across J. Paul Morrison's (RIP) book "Flow-Based Programming" after we had already started working on Flyde, and we were thrilled to find that many of the concepts we had been developing were already well-established in the FBP community.
+
+However, Flyde does not strictly adhere to the FBP paradigm. We have made some deviations from the traditional FBP model and do not see following FBP as a goal in itself. Instead, we aim to create a visual programming language that is practical and useful for modern software development.
+
+## How does Flyde compare to other visual programming languages?
+
+### NodeRED
+
+Flyde integrates directly into TypeScript/JavaScript projects, acting as a visual layer within the code rather than an external service. It's designed to embed visual flows at any level of your application, from detailed business logic to overarching services, offering a seamless blend with existing codebases.
+
+### Scratch
+
+While Scratch is an excellent educational tool for beginners, Flyde is tailored for real developers. It adopts a functional, reactive approach and is designed to work within the ecosystems developers are already familiar with, like IDEs, without simplifying the complexity required for professional backend development.
+
+### Enso
+
+Enso targets data science with a unique IDE and programming language, focusing on data processing. In contrast, Flyde is application-centric, aiming to streamline backend development without introducing new tooling or languages, sticking closely to the existing TypeScript/JavaScript ecosystem.
+
+### n8n / Zapier / Integromat / PipeDream
+
+Unlike these automation platforms, which often work as closed systems for connecting APIs, Flyde is open-source and embeddable within your project. This gives developers the flexibility to craft detailed flows, from recursion to precise HTTP requests, offering a granular level of control and customization not typically available in no-code/low-code automation tools.

website/docs/6-testing-deploying.md

@@ -6,6 +6,6 @@ A great example is the standard library, which has some tests that use Flyde flo
 
 Same goes for deployment, you can use any deployment tool you like. You can use a CI/CD pipeline, a serverless framework, or even a simple bash script.
 
-:::info
+<!-- :::info
 If you're looking for a way to deploy your flows as a service, check out [Trigg](https://www.trigg.dev), a serverless platform for Flyde.
-:::
+::: -->

website/docs/7-advanced-concepts.md

@@ -3,11 +3,6 @@
 Flyde was built with flexibility and power in mind. To enable that, Flyde tries to be reactive and declarative.
 This enables building custom flows and custom nodes with little overhead and boilerplate.
 
-:::note
-In this article a differentiation between a node and a node instance will be made. A node is the definition of a node, and a node instance is a specific instance of a node in a flow.
-Configuring a node instance is done using the visual editor on a flow that uses the node, while configuring a node is done by changing it's source code.
-:::
-
 ## Node Instance Input Modes
 
 Each input of each instance of a node in a flow can be in one of the following modes:
@@ -38,17 +33,23 @@ When a node starts running, it'll "consume" the values from its inputs and perfo
 
 While a node is running, new values will only take effect on the next time it runs, unless they are set as a "reactive input". More on that below.
 
-A node can have implicit or explicit completion triggers.
+A node can have implicit or explicit completion triggers. More on that below.
+
+### 'Completed' and 'Error'
 
-#### Implicit Completion
+While not real "states", a node can be in a "completed" state or an "error" state. A node is considered "completed" when it has finished running and has no more work to do. A node is considered in an "error" state when it has thrown an error during its run. Both completed and error states are transient, and a node will go back to the "idle" state after it has completed or errored.
+
+## Node Completion
+
+### Implicit Completion
 
 A node will implicitly complete when it has no more work to do. For code nodes, it means that their `run` method has returned. In case the `run` method returns a promise, the node will implicitly complete when the promise resolves.
 
 For visual nodes, it means that all of its children have completed.
 
 Implicit completion is the default behavior for nodes.
 
-#### Explicit Completion
+### Explicit Completion
 
 A node can declare it has explicit completion by declaring a "completionOutputs" property. This property is an array of output names that will trigger the node to complete when they emit a value. It also supports a `+` operator to declare that all outputs should trigger completion.
 
@@ -60,25 +61,27 @@ For example:
 
 Visual nodes' completion outputs can be declared explicitly as well by right-clicking the node and selecting "Set Completion Outputs".
 
-### 'Completed' and 'Error'
-
-While not real "states", a node can be in a "completed" state or an "error" state. A node is considered "completed" when it has finished running and has no more work to do. A node is considered in an "error" state when it has thrown an error during its run. Both completed and error states are transient, and a node will go back to the "idle" state after it has completed or errored.
-
 ## Reactive Inputs
 
 A node can declare that an input is "reactive". This means that the node will re-run when the input emits a new value, even if the node is already running.
 
-A great example of when this is useful is a "debounce" node. Imagine a "debounce" node with 2 inputs: `value` and `delay`. Once a value is received, the node needs to remain in "running" state for the duration of the delay, and then emit the value. But if a node only accepts new values when it is idle, it will not be able to accept the new value of `value` until it has completed. To solve this, we can mark the `value` input as "reactive", and the node will re-run when the `value` input emits a new value. Updating the `delay` input will not trigger a re-run, as it is not marked as "reactive", and will only take effect on the next time the node runs.
+A great example of when this is useful is a "debounce" node. Imagine a "debounce" node with 2 inputs: `value` and `delay`. Once a value is received, the node needs to remain in "running" state for the duration of the delay, and then emit the value. But if a node only accepts new values when it is idle, it will not be able to accept the new value of `value` until it has completed.
+
+To solve this, we can mark the `value` input as "reactive", and the node will re-run when the `value` input emits a new value. Updating the `delay` input will not trigger a re-run, as it is not marked as "reactive", and will only take effect on the next time the node runs.
 
 ## "Manually" Triggering a Node
 
 By default, a node will run when all of its inputs are satisfied. But sometimes you might want to control when a node runs more granularly. To do so, you may expose a "Trigger" input, which will act as a manual trigger for the node. If this input is connected, the node will only run when it receives a value on the "Trigger" input (and all other inputs are satisfied).
 
 To expose the "trigger" input, right-click the node instance and select the "Show Trigger" option.
 
+_[ TODO: Add a gif showing how to expose the trigger input]_
+
 ## Error Handling
 
 When a node throws an error, it will be in an "error" state. The error will be displayed in the node's UI, and the error will be propagated to the parent node/flow.
 
 To "catch" an error and avoid it from propagating, you can expose the "Error" special output.
 To expose the "Error" output, right-click the node instance and select the "Show output Error" option.
+
+_[ TODO: Add a gif showing how to expose the trigger input]_

website/docs/9-troubleshooting.md

@@ -1,10 +1,28 @@
 # Troubleshooting
 
-:::warning
-This article is a work in progress. It will be updated with more information soon.
-:::
+## Visual Debugger
 
-Topics this will cover:
+Flyde comes with a visual debugger that can help you troubleshoot your flows. When using the "test flow" feature from the editor, you can see the flow's execution in real-time, and inspect the values of each node's inputs and outputs.
 
-- visual debugger
-- extension troubleshooting tips
+When running flows locally using the `@flyde/runtime` package, the runtime will try to connect to the local debugger server running from the visual editor automatically. If you're running the visual editor locally, you can see the flow's execution in real-time, and inspect the values of each node's inputs and outputs.
+
+## Extension Troubleshooting
+
+If something in the extension is not working as expected, you can look for errors in VSCode's dev tools. To do so, open the command palette and search for "Developer: Toggle Developer Tools". This will open a new window with the dev tools, where you can see errors and logs from everything running in VSCode, including the Flyde extension.
+
+## Flow Runtime Troubleshooting
+
+### Verbose Logging
+
+Behind the scenes, Flyde uses the `debug` package to log debug information. You can enable debug logs by setting the `DEBUG` environment variable to `flyde:*`. For example, on a Unix-like system, you can run the following command to enable debug logs:
+
+```sh
+DEBUG=flyde:* node my-flow.js
+```
+
+## Reporting Issues
+
+We're always looking to improve Flyde, and we'd love to hear from you. If you find a bug, have a feature request, or just want to ask a question, feel free to:
+
+- open an issue on the [Flyde GitHub repository](https://www.github.com/flydelabs/flyde)
+- join our [Discord server](https://discord.com/invite/x7t4tjZQP8) and ask in the #flyde channel

website/scripts/build-stdlib-docs.ts

@@ -64,6 +64,6 @@ const groupAndTables = entries.map(([ns, nodes]) => {
     { groups: groupAndTables }
   );
 
-  writeFileSync("docs/reference/StdLib/index.md", contents);
-  console.log(`Done writing docs/reference/StdLib/index.md`);
+  writeFileSync("docs/Reference/StdLib/index.md", contents);
+  console.log(`Done writing docs/Reference/StdLib/index.md`);
 })();