docs: add better documentation

docs/README.md

@@ -0,0 +1,14 @@
+# Documentation
+
+Welcome to the documentation for the **Hetzner Cloud CLI**.
+
+This documentation is written and organized following the [Diátaxis](https://diataxis.fr/) guidelines. Below you can find a high-level overview of where to look for certain things:
+
+- [Tutorials](tutorials)
+- [Guides](guides)
+- [Reference](reference/hcloud.md)
+
+## Getting help
+
+- 🐛 Report bugs using [our issue tracker](https://github.com/hetznercloud/cli/issues/new?template=bug.yaml).
+- 🙋 If you need help, reach us using the [Support Center](https://console.hetzner.cloud/support).

docs/guides/README.md

@@ -0,0 +1,5 @@
+# Guides
+
+This folder contains guides on how to accomplish specific tasks with the Hetzner Cloud CLI.
+
+- [Using output options](using-output-options.md)

docs/guides/using-output-options.md

@@ -0,0 +1,167 @@
+# Using output options
+
+The CLI allows you to customize the output format of some commands using the `--output` flag. 
+This guide shows you how to use this feature and use it in combination with other tools.
+
+## JSON
+
+`describe`, `list` and `create` commands support JSON output format. To use it, simply add the `--output json` flag to your command.
+
+For example, to get the details of a location in JSON format, you can use the following command:
+
+```bash
+$ hcloud location describe fsn1 --output json
+{
+  "id": 1,
+  "name": "fsn1",
+  "description": "Falkenstein DC Park 1",
+  "country": "DE",
+  "city": "Falkenstein",
+  "latitude": 50.47612,
+  "longitude": 12.370071,
+  "network_zone": "eu-central"
+}
+```
+
+You can combine this with other tools to process the output. For example, you can use `jq` to filter the output:
+
+```bash
+$ hcloud location describe fsn1 --output json | jq '.name'
+"fsn1"
+```
+
+```bash
+$ hcloud location describe fsn1 --output json | jq '{id, name}'
+{
+  "id": 1,
+  "name": "fsn1"
+}
+```
+
+`list` commands return a list of objects in JSON format. For example, to get a list of all locations in JSON format, you can use the following command:
+
+```bash
+$ hcloud location list --output json
+[
+  {
+    "id": 1,
+    "name": "fsn1",
+    "description": "Falkenstein DC Park 1",
+    "country": "DE",
+    "city": "Falkenstein",
+    "latitude": 50.47612,
+    "longitude": 12.370071,
+    "network_zone": "eu-central"
+  },
+  {
+    "id": 2,
+    "name": "nbg1",
+    "description": "Nuremberg DC Park 1",
+    "country": "DE",
+    "city": "Nuremberg",
+    "latitude": 49.452102,
+    "longitude": 11.076665,
+    "network_zone": "eu-central"
+  },
+  ...
+]
+```
+
+Once again, you can use `jq` to filter the output. Following example shows how to get the names of all locations of which the network zone is `eu-central`:
+
+```bash
+$ hcloud location list --output json | jq '[.[] | select(.network_zone == "eu-central") | .name]'    
+[
+  "fsn1",
+  "nbg1",
+  "hel1"
+]
+```
+
+## YAML
+
+`describe`, `list` and `create` commands support YAML output format as well.
+
+```bash
+$ hcloud location describe fsn1 --output yaml
+id: 1
+name: fsn1
+description: Falkenstein DC Park 1
+country: DE
+city: Falkenstein
+latitude: 50.47612
+longitude: 12.370071
+network_zone: eu-central
+```
+
+For YAML, you can use `yq` instead of `jq`.
+
+
+```bash
+$ hcloud location list --output yaml | yq '.[] | [{"id": .id, "name": .name}]'
+- id: 1
+  name: fsn1
+- id: 2
+  name: nbg1
+- id: 3
+  name: hel1
+- id: 4
+  name: ash
+- id: 5
+  name: hil
+- id: 6
+  name: sin
+```
+
+## Go Template Format
+
+`describe` commands support the Go string template format as well. You can read up on the syntax in the 
+[Go documentation](https://pkg.go.dev/text/template/). The data structures passed to the template are defined
+by our API and can be found in [hcloud-go](https://pkg.go.dev/github.com/hetznercloud/hcloud-go/v2/hcloud/schema).
+
+For example, you could obtain the number of cores of a server using the following command:
+
+```bash
+$ hcloud server describe my-server --output format='{{.ServerType.Cores}}'
+2
+```
+
+## Table options
+
+`list` commands support table options as well. These options allow you to customize the output format of the output table,
+if not using JSON or YAML.
+
+> [!NOTE]
+> You can also combine both of the below options to use them at once: ``--output noheader --output columns=id,name,network_zone``
+
+### noheader
+
+This option removes the header from the output table.
+
+```bash
+$ hcloud location list --output noheader 
+1   fsn1   Falkenstein DC Park 1   eu-central     DE   Falkenstein  
+2   nbg1   Nuremberg DC Park 1     eu-central     DE   Nuremberg    
+3   hel1   Helsinki DC Park 1      eu-central     FI   Helsinki     
+4   ash    Ashburn, VA             us-east        US   Ashburn, VA  
+5   hil    Hillsboro, OR           us-west        US   Hillsboro, OR
+6   sin    Singapore               ap-southeast   SG   Singapore   
+```
+
+### columns
+
+This option allows you to filter by columns.
+
+```bash
+$ hcloud location list --output columns=id,name,network_zone 
+ID   NAME   NETWORK ZONE
+1    fsn1   eu-central  
+2    nbg1   eu-central  
+3    hel1   eu-central  
+4    ash    us-east     
+5    hil    us-west     
+6    sin    ap-southeast
+```
+
+Using the ``--help`` flag will show you a list of all available columns for this command. Note that these might include
+more than the default columns.

docs/tutorials/README.md

@@ -0,0 +1,6 @@
+# Tutorials
+
+This folder contains tutorials for the Hetzner Cloud CLI.
+
+- [Setup the hcloud CLI](setup-hcloud-cli.md)
+- [Creating a server](create-a-server.md)

docs/tutorials/create-a-server.md

@@ -0,0 +1,108 @@
+# Creating a server
+
+This tutorial covers the process of creating a server using the Hetzner Cloud CLI. It includes creating an SSH Key, 
+uploading it, creating a Server and then connecting to it via SSH.
+
+## Prerequisites
+
+- A functioning installation of the [hcloud CLI](setup-hcloud-cli.md), with a valid active context.
+
+## 1. Create an SSH Key
+
+### 1.1 Generate an SSH Key
+
+While an SSH key is not strictly required to create a server, it is highly recommended for secure access.
+If you don't have an SSH key yet, you can generate one using the following command:
+
+```bash
+ssh-keygen -t ed25519 -f ~/.ssh/hcloud
+```
+
+Your private key will now be located at `~/.ssh/hcloud`. **Do not share your private key with anyone!**
+
+### 1.2 Upload the SSH Key
+
+You can upload your SSH key to Hetzner Cloud using the following command:
+
+```bash
+hcloud ssh-key create --name my-ssh-key --public-key-from-file ~/.ssh/hcloud.pub
+```
+
+> [!TIP]
+> You can set this SSH key as the default SSH key for your context using the following command:
+> ```bash
+> hcloud config set default-ssh-keys my-ssh-key
+> ```
+
+## 2. Create a Server
+
+### 2.1 Pick a Server Type
+
+Before creating a server, you need to choose a server type. You can list all available server types using the following command:
+
+```bash
+hcloud server-type list
+```
+
+For this example we will use the `cpx11` server type.
+You can view the details of this server type using the following command:
+
+```bash
+hcloud server-type describe cpx11
+```
+
+### 2.2 Pick an Image
+
+You need to choose an image for your server. You can list all available images using the following command:
+
+```bash
+hcloud image list
+```
+
+There are many images available, including various Linux distributions and pre-configured app images.
+For this example we will use the `ubuntu-24.04` image.
+
+### 2.3 Pick a Location (Optional)
+
+You can choose a location for your server. You can list all available locations using the following command:
+
+```bash
+hcloud location list
+```
+
+If you don't specify a location, one will be chosen for you. This is what we will do in this example.
+
+### 2.4 Create the Server
+
+Now you can create the server using the following command:
+
+```bash
+hcloud server create --name my-server --type cpx11 --image ubuntu-24.04 --ssh-key my-ssh-key
+```
+
+If you set the SSH key as the default SSH key for your context, you can omit the `--ssh-key` flag.
+After the server was created, you will see information about the server, including its IP address.
+
+## 3. Connect to the Server
+
+You can connect to the server using SSH. The CLI contains a built-in utility to do this:
+
+```bash
+hcloud server ssh my-server -i ~/.ssh/hcloud
+```
+
+This command will open an SSH connection to the server using the private key you generated earlier.
+
+## 4. Clean Up
+
+After you are done with the server, you can delete it using the following command:
+
+```bash
+hcloud server delete my-server
+```
+
+You can also delete the SSH key using the following command:
+
+```bash
+hcloud ssh-key delete my-ssh-key
+```