Update the docs dev documentation (#253)

* Update the documenation content

* Point guide to handbook

content/docs/product/docs/_index.md

@@ -18,11 +18,11 @@ Our goal is to have all documentation for our product be available via that site
 
 Our responsibilities for public documentation are layered.
 
-- Ownership for content is assigned **according to team or SIG responsibilities**. For example, Team Horizon "owns" articles related to [Developer Platform Overview](https://github.com/giantswarm/docs/blob/main/src/content/vintage/platform-overview/_index.md) as you can see on the front matter (defined by the YAML header fields).
+- Ownership for content is assigned **according to team or SIG responsibilities**. For example, SIG product "owns" the article [overview introduction](https://github.com/giantswarm/docs/blob/main/src/content/overview/introduction/_index.md) as you can see on the front matter (defined by the YAML header fields).
 
 - SIG Docs is responsible for overall content coherence and consistency.
 
-- SIG User Experience (UX) takes responsibility for the overall UI and user experience, having the docs site online and available, have a user-friendly search etc.
+- Team Horizon takes responsibility for the overall structure and functionality, meanwhile Honeybadger is responsible for the operations.
 
 ## Editing content
 
@@ -40,16 +40,14 @@ For pull requests, **seek an agreement and approval within your team first**. Th
 
 Once a pull request in the giantswarm/docs repository gets merged, the changes get published.
 
-> (Under the hood, a new release is created using GitHub actions, immediately after the merge. Then, up to 10 minutes later, the release gets published via the `app-updater-app` on `gollum`. The app for serving `docs.giantswarm.io` lives in workload cluster `c68pn` on `gollum` installation, in the `docs` namespace.)
+> (Under the hood, a new release is created using GitHub actions, immediately after the merge. Then, up to 10 minutes later, the release gets published via the `app-updater-app` on `gazelle`. The app for serving `docs.giantswarm.io` lives in workload cluster `operations` on `gazelle` installation, in the `docs` namespace.)
 
-In the unlikely case that you don't want your changes to be released immediately (e. g. because you want to craft a release manually), simply add
+In the unlikely case that you don't want your changes to be released immediately (e. g. because you want to craft a release manually), simply add the following text to your final commit message when merging:
 
 ```nohighlight
 do not release
 ```
 
-to your final commit message when merging.
-
 ### When to merge a docs PR
 
 Changes to the docs content should be merged as soon as the content is relevant for users.
@@ -66,14 +64,13 @@ When adding content, several questions have to be answered:
 - Where should that page title live?
 - What customer/user question(s) does this article answer?
 
-Feel free to ping SIG Docs to discuss these questions, or join the weekly sync/special working hours call.
+Every section has a template reference which helps to create a new entry suggesting an outline and giving some clues about the content. Feel free to ping SIG Docs to discuss these questions, or join the weekly sync/special working hours call.
 
 ## Style
 
-When writing documentation, there is a lot to be taken care of in terms of tonality, style, voice, and even formatting.
+When writing documentation, there is a lot to be taken care of in terms of tonality, style, voice, and even formatting. We have written a [style guide](https://handbook.giantswarm.io/docs/content/style-guide/) for all written content that follows the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/).
 
-Feel free to give feedback to SIG Docs regarding what you would like to see guidelines for.
-Information beyond the details below can be found in the [content styleguide](https://docs.google.com/document/d/1TKzd70koVmrJyXx0JOe15tK0-mIiGYkP3gz_2BxM844/edit).
+Here we describe some specifics for our customer face documentation. Feel free to give feedback to SIG Docs if you have any suggestions or questions about this recommendations.
 
 ### Writing goals and principles
 
@@ -169,6 +166,7 @@ gsctl create cluster \
   --owner acme \
   --create-default-nodepool false
 ```
+
 ## Product feature naming
 
 When mentioning a feature, please make sure to use exactly the naming we decided on previously. If there is a canonical name for your feature, you should be able to find it in the [glossary]({{< relref "/docs/glossary/_index.md" >}}). If there isn't one, please kick off a discussion with SIG Product.

content/docs/product/docs/docs-dev.md

@@ -6,37 +6,34 @@ description: >
   This section explains how the docs development environment works and how to work with it locally.
 ---
 
-# Developing on the docs
+## Developing on the docs
 
-## Repository overview
+### Repository overview
 
-The repository named `docs` holds the main **content** of our documentation. The documentation site is created using the static site generator [HUGO](http://gohugo.io/) based on Markdown files in the `src/content/` directory of the `docs` reository.
+The repository named `docs` holds the main **content** of our documentation. The documentation site is created using the static site generator [HUGO](http://gohugo.io/) based on Markdown files in the `src/content/` directory of the `docs` repository.
 
 Additional content is tied in through the scripts
 
 - `scripts/aggregate-changelogs`: Aggregates changelog entries into the `src/content/changes` destination.
-- `scripts/update-crd-reference`: Generates reference pages for our custom resource definitions in the `src/content/reference/management-api` destination.
+- `scripts/update-crd-reference`: Generates reference pages for our custom resource definitions in the `src/content/reference/platform-api` destination.
+- `update-helm-chart-reference`: Generates reference pages for our Helm charts in the `src/content/reference/platform-api` destination.
 - `scripts/update-external-repos`: Tutorials that need their own code repository. They must have a `docs` subfolder with the Markdown content and optionally some images. Configuration is found in `scripts/update-external-repos/repositories.txt`.
 
 To update these external content types, the `Makefile` provides specific targets:
 
 - `make changes`
 - `make update-external-repos`
 - `make update-crd-reference`
+- `make update-cluster-app-reference`
 
-## Related repositories and components
+There are two GitHub Actions workflows that run these scripts automatically:
 
-There are several additional repositories which provide additional functionality:
+- `Update generated content`: It runs every day in the morning and creates or update the `Semi-automatic update of generated content` pull requests with the changes from the different sources.
+- `Merge generated content updates`: It runs every Friday and merges the `Semi-automatic update of generated content` pull request to release automatically the changes.
 
-- [docs-proxy](https://github.com/giantswarm/docs-proxy/): nginx proxy server which integrates the search engine and the API spec (see below) into the documentation site, and provides some additional configuration, e. g. regarding HTTP headers.
+**Note**: In order to publish the release information or other automatic generated content, you need to run the `Update generated content` manually and merge the pull request generated after review the changes.
 
-- [api-spec](https://github.com/giantswarm/api-spec/): Specification (in Swagger/OpenAPI) format for the Giant Swarm REST API. Available in the docs site under https://docs.giantswarm.io/api/.
-
-- [sitesearch](https://github.com/giantswarm/sitesearch/): Search engine for the documentation site.
-
-- [indexer](https://github.com/giantswarm/docs-indexer/): Indexing tool that pushes new content to the `sitesearch` index periodically, to keep the search engine up-to-date.
-
-## Iterating on content locally
+### Iterating on content locally
 
 If you want to iterate quickly on some content you can use the `make dev`
 command.
@@ -45,7 +42,7 @@ You can access the server at `http://localhost:1313/`. The server can be stopped
 
 It will not include content from the external repositories.
 
-### Previewing changes
+#### Previewing changes
 
 You can bring up the final site using the following commands:
 
@@ -56,15 +53,15 @@ docker-compose up
 
 You can access the server at `http://localhost:8080/`. The server can be stopped by hitting `Ctrl + C`.
 
-## Shortcodes
+### Shortcodes
 
 Shortcodes allow the use of a string in any number of places in the docs, while maintaining it only in one place. We use these to place, for example, configuration details.
 
 The goal here is to give users accurate, complete and up-to-date information.
 
 Shortcodes exist as one file each in the folder [src/layouts/shortcodes](https://github.com/giantswarm/docs/tree/master/src/layouts/shortcodes).
 
-### Usage
+#### Usage
 
 A shortcode can only be placed in *Markdown* text. The file name (without `.html` suffix) is used as a placeholder, wrapped in a certain way, like
 
@@ -85,7 +82,7 @@ and would get rendered like
 ... since version 6.3.0 ...
 ```
 
-### List of shortcodes with explanation
+#### List of shortcodes with explanation
 
 - `platform_support_table`: A table that displays information regarding which
 providers support a feature described in the context. Look for examples in the
@@ -134,7 +131,7 @@ spotinstances for AWS.
 - `minimal_supported_cluster_size_worker_nodes`: The minimum number of worker
 nodes a cluster must have in order to be supported by Giant Swarm.
 
-## About the Header and Footer
+### About the Header and Footer
 
 The header and footer are to be kept in sync with www.giantswarm.io
 In order to do this we copy the HTML and CSS specific to those parts of the page.
@@ -164,8 +161,7 @@ and behave correctly.
 `scripts/gs_menu.js`      - Hand written javascript that recreates the interactive
                             functionality of the navigation menus.
 
-
-## Deploying
+### Deploying
 
 To publish the content in this repository, a release is needed. Releases are created automatically for every push to the `master` branch, so normally whenever a pull request gets merged. [app-updater](https://github.com/giantswarm/app-updater) then updates the `docs-app` app CR on `gollum`.
 
@@ -183,9 +179,9 @@ To check locally whether all internal links are correct, use `make linkcheck`.
 
 To check both internal and external links, use `make linkcheck-external`.
 
-## Solutions for specific problems
+### Solutions for specific problems
 
-### Kubernetes API versions
+#### Kubernetes API versions
 
 Keep an eye on API versions of Kubernetes resources.
 
@@ -197,11 +193,11 @@ Keep an eye on API versions of Kubernetes resources.
 
 An example for this would be the deprecation of the API version of Ingress resources from `networking.k8s.io/v1beta1` to `networking.k8s.io/v1` in Kubernetes 1.19.
 
-## Editing content
+### Editing content
 
 Edit existing content in the `src/content` folder of the docs repository.
 
-### Front matter
+#### Front matter
 
 Each documentation page consists of a Markdown file that starts with some metadata called [front matter](https://gohugo.io/content-management/front-matter/). Some hints:
 
@@ -215,7 +211,7 @@ Special front matter fields we use:
 - `owner`: List of GitHub team URLs for the team(s) or SIG(s) owning the page. The owning team/SIG is the one responsible for keeping the content up-to-date and useful.
 - `user_questions`: List of questions this article answers. Written from a user's perspective. E. g. _How do I ..._.
 
-### Hyperlinks
+#### Hyperlinks
 
 In order to link to other docs pages, please use this format only:
 
@@ -231,7 +227,7 @@ Note that
 
 This is important to support automation when links have to change, or when checking links.
 
-### Table of contents and headline anchors
+#### Table of contents and headline anchors
 
 The rendered documentation pages will have a table of contents on the left hand side and an anchor for every intermediate headline. This anchor is normally generated from the headline's content. For example, a headline