docs: Rewrite entry and "first pipeline" page

.cspell.json

@@ -57,6 +57,7 @@
     "Fogas",
     "forbidigo",
     "Forgejo",
+    "FOSS",
     "fsnotify",
     "Geeklab",
     "Georgiana",

docs/docs/10-intro/index.md

@@ -1,26 +1,33 @@
 # Welcome to Woodpecker
 
-Woodpecker is a CI/CD tool. It is designed to be lightweight, simple to use and fast. Before we dive into the details, let's have a look at some of the basics.
+Woodpecker is a CI/CD tool. It is designed to be lightweight (< 200 MB memory consumption), simple to use and fast and can be used with many different Git providers and backends (docker, kubernetes, local).
 
-## Have you ever heard of CI/CD or pipelines?
+## The "CI/CD" concept
 
-Don't worry if you haven't. We'll guide you through the basics. CI/CD stands for Continuous Integration and Continuous Deployment. It's basically like a conveyor belt that moves your code from development to production doing all kinds of
-checks, tests and routines along the way. A typical pipeline might include the following steps:
+CI/CD stands for "Continuous Integration” and “Continuous Deployment.”
+It is a streamlined process that moves your code from development to production while performing various checks, tests, and routines along the way.
+A standard CI/CD pipeline typically includes steps such as:
 
 1. Running tests
-2. Building your application
-3. Deploying your application
+2. Building the application
+3. Deploying the application
 
-[Have a deeper look into the idea of CI/CD](https://www.redhat.com/en/topics/devops/what-is-ci-cd)
+RedHat has written an [article which explains the concept in more detail](https://www.redhat.com/en/topics/devops/what-is-ci-cd).
 
-## Do you know containers?
+## Containers at the core
 
-If you are already using containers in your daily workflow, you'll for sure love Woodpecker. If not yet, you'll be amazed how easy it is to get started with [containers](https://opencontainers.org/).
+In contrast to other CI/CD applications, Woodpecker solely focuses on using containers for executing workflows.
+If you are already using containers in your daily workflow, you'll for sure love Woodpecker.
 
-## Already have access to a Woodpecker instance?
+## FOSS
 
-Then you might want to jump directly into it and [start creating your first pipelines](../20-usage/10-intro.md).
+Woodpecker is Free-and-Open-Source Software (FOSS), licensed under the Apache-2.0 license.
+Hence, it does not come with any license cost and this will never change.
 
-## Want to start from scratch and deploy your own Woodpecker instance?
+Woodpecker has been forked from Drone CI in 2019 after the project has changed it license.
+The full history is available in [the about section](../50-about.md#history).
 
-Woodpecker is [pretty lightweight](../30-administration/00-getting-started.md#hardware-requirements) and will even run on your Raspberry Pi. You can follow the [deployment guide](../30-administration/00-getting-started.md) to set up your own Woodpecker instance.
+## Getting started
+
+Woodpecker is [pretty lightweight](../30-administration/00-getting-started.md#hardware-requirements) and can even run on a Raspberry Pi without much impact.
+To set up your own Woodpecker instance, follow the [deployment guide](../30-administration/00-getting-started.md).

docs/docs/20-usage/10-intro.md

@@ -1,19 +1,20 @@
-# Your first pipeline
+# "Hello world"
 
-Let's get started and create your first pipeline.
+Let's get started and create a simple pipeline to demonstrate the pipeline syntax and overall behavior.
 
 ## 1. Repository Activation
 
-To activate your repository in Woodpecker navigate to the repository list and `New repository`. You will see a list of repositories from your forge (GitHub, Gitlab, ...) which can be activated with a simple click.
+To enable your repository in Woodpecker, navigate to the repository list and select **New Repository**.
+You’ll be presented with a list of repositories from your forge (e.g., GitHub, GitLab) that can be activated with a simple click.
+Ensure you have administrative rights on the repository in your forge, as Woodpecker needs to add a webhook to detect events like pushes, pull requests, and tags. 
 
 ![new repository list](repo-new.png)
 
-To enable a repository in Woodpecker you must have `Admin` rights on that repository, so that Woodpecker can add something
-that is called a webhook (Woodpecker needs it to know about actions like pushes, pull requests, tags, etc.).
+## 2. The first workflow
 
-## 2. Define first workflow
-
-After enabling a repository Woodpecker will listen for changes in your repository. When a change is detected, Woodpecker will check for a pipeline configuration. So let's create a file at `.woodpecker/my-first-workflow.yaml` inside your repository:
+Once your repository is enabled, Woodpecker starts monitoring it for changes.
+When a change is detected, it looks for a pipeline configuration file.
+To set up your first workflow, create a file named `.woodpecker/my-first-workflow.yaml` (feel free to change the file name to your liking) in your repository:
 
 ```yaml title=".woodpecker/my-first-workflow.yaml"
 when:
@@ -22,21 +23,20 @@ when:
 
 steps:
   - name: build
-    image: debian
+    image: debian:latest
     commands:
       - echo "This is the build step"
       - echo "binary-data-123" > executable
-  - name: a-test-step
-    image: golang:1.16
+  - name: test
+    image: golang:latest
     commands:
       - echo "Testing ..."
       - ./executable
 ```
 
 **So what did we do here?**
 
-1. We defined your first workflow file `my-first-workflow.yaml`.
-2. This workflow will be executed when a push event happens on the `main` branch,
+1. This workflow will be executed when a `push` event happens on the `main` branch,
    because we added a filter using the `when` section:
 
    ```diff
@@ -47,64 +47,61 @@ steps:
    ...
    ```
 
-3. We defined two steps: `build` and `a-test-step`
-
-The steps are executed in the order they are defined, so `build` will be executed first and then `a-test-step`.
+1. We defined two steps: `build` and `test`
 
-In the `build` step we use the `debian` image and build a "binary file" called `executable`.
+The steps in your workflow are executed sequentially in the order they are defined.
+For instance, the `build` step will run first, followed by the `test` step.
 
-In the `a-test-step` we use the `golang:1.16` image and run the `executable` file to test it.
+- In the `build` step, the workflow uses the debian image to create a binary file named executable.
+- In the `test` step, the workflow uses the `golang:latest` image to run the executable file for testing.
 
-You can use any image from registries like the [Docker Hub](https://hub.docker.com/search?type=image) you have access to:
+You can use any image any registry you have access to.
+The most common one is [Docker Hub](https://hub.docker.com/search?type=image) which is implicitly used via `docker.io` as the default registry.
+If you want to use a different one, you need to prefix the registry explicitly:
 
 ```diff
  steps:
    - name: build
 -    image: debian
-+    image: my-company/image-with-aws_cli
-     commands:
-       - aws help
++    image: my-registry/my-repo/my-image:latest
 ```
 
-## 3. Push the file and trigger first pipeline
+## 3. Push the file and trigger the first pipeline
 
-If you push this file to your repository now, Woodpecker will already execute your first pipeline.
+If you commit and push this file to your repository, Woodpecker will execute the pipeline.
 
 You can check the pipeline execution in the Woodpecker UI by navigating to the `Pipelines` section of your repository.
 
 ![pipeline view](./pipeline.png)
 
-As you probably noticed, there is another step in called `clone` which is executed before your steps. This step clones your repository into a folder called `workspace` which is available throughout all steps.
-
-This for example allows the first step to build your application using your source code and as the second step will receive
-the same workspace it can use the previously built binary and test it.
+As you probably noticed, there is another step called `clone` which is executed before your steps.
+This step is required to initially clone your repository into a directory named `workspace`.
+This directory will be available throughout all steps and provide the pipeline access to the files.
+As this is always required to get started, Woodpecker adds this step implicitly.
+There are ways to [alter/omit this step](./20-workflow-syntax.md#clone) for specific use cases, but this is out-of-scope for getting started.
 
 ## 4. Use a plugin for reusable tasks
 
-Sometimes you have some tasks that you need to do in every project. For example, deploying to Kubernetes or sending a Slack message. Therefore you can use one of the [official and community plugins](/plugins) or simply [create your own](./51-plugins/20-creating-plugins.md).
+Woodpecker plugins are steps that aim to simplify the execution of frequently used tasks.
+They also come with restricted modification functionality, which reduces the potential attack surface, for example by disallowing the use of arbitrary environment variables.
+The Woodpecker team maintains a set of official plugins.
+In addition, there are many community plugins available from various contributors.
+Most can be found in the [Plugin registry](https://woodpecker-ci.org/plugins), but you will surely also find additional ones out in the wild.
+
+If you want to create your own plugin, take a look at our [plugin guide](./51-plugins/20-creating-plugins.md).
+
+The key differences between plugins and regular steps in Woodpecker are:
 
-If you want to get a Slack notification after your pipeline has finished, you can add a Slack plugin to your pipeline:
+- No `environment:` section: Plugins do not support the use of the `environment:` section for defining environment variables.
+- Dedicated `settings:` section: Plugins utilize a specific `settings:` section to configure their options and behavior.
 
 ```yaml
 steps:
-  # ...
-  - name: notify me on Slack
-    image: plugins/slack
+  - name: Upload to S3
+    image: woodpeckerci/plugin-s3:latest
     settings:
-      channel: developers
-      username: woodpecker
-      password:
-        from_secret: slack_token
-    when:
-      status: [success, failure] # This will execute the step on success and failure
+      bucket: my-bucket-name
+      access_key: my-access-key
+      secret_key:
+        from_secret: secret_key
 ```
-
-To configure a plugin you can use the `settings` section.
-
-Sometime you need to provide secrets to the plugin. You can do this by using the `from_secret` key. The secret must be defined in the Woodpecker UI. You can find more information about secrets [here](./40-secrets.md).
-
-Similar to the `when` section at the top of the file which is for the complete workflow, you can use the `when` section for each step to define when a step should be executed.
-
-Learn more about [plugins](./51-plugins/51-overview.md).
-
-As you now have a basic understanding of how to create a pipeline, you can dive deeper into the [workflow syntax](./20-workflow-syntax.md) and [plugins](./51-plugins/51-overview.md).