diff --git a/README.md b/README.md
index 07ba3f3cc4..98ef036a0e 100644
--- a/README.md
+++ b/README.md
@@ -1,216 +1,147 @@
- [中文](./README_CN.md) [](https://gitpod.io/#https://github.com/jenkins-x/jx-docs)
+# Jenkins X Documentation
-# Jenkins X Docs
+[](https://gitpod.io/#https://github.com/jenkins-x/jx-docs)
+[中文文档](./README_CN.md)
-
+This repository contains the source files for [jenkins-x.io](http://jenkins-x.io/). For the best experience, please read the documentation at [jenkins-x.io](http://jenkins-x.io/) as some links may not work when viewing directly in this repository.
-This repository contains the source files for [jenkins-x.io](http://jenkins-x.io/)
-
-**NOTE:** Please browse these docs on [jenkins-x.io](http://jenkins-x.io/). Not all links work when browsing the Markdown files inside this repository.
-
----
-
-
-
-- [Building the docs](#building-the-docs)
- - [Preparing the sources](#preparing-the-sources)
- - [Git submodules](#git-submodules)
- - [Downloading npm modules](#downloading-npm-modules)
- - [Running Hugo](#running-hugo)
- - [Locally](#locally)
- - [Dockerized](#dockerized)
-- [Common Workflows](#common-workflows)
- - [Running spell check](#running-spell-check)
- - [Checking links, images, etc](#checking-links-images-etc)
- - [Adding redirects](#adding-redirects)
- - [Upgrading the enhancements content](#upgrading-the-enhancements-content)
-- [Localization](#localization)
+## Table of Contents
+- [Prerequisites](#prerequisites)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Building the Documentation](#building-the-documentation)
+- [Development Tools](#development-tools)
+- [Content Management](#content-management)
- [Contributing](#contributing)
-
-
----
-
-## Building the docs
+## Prerequisites
-
+- Git
+- Node.js and npm
+- Hugo (see [Makefile](./Makefile) for recommended version)
+- Docker (optional, for containerized development)
-### Preparing the sources
-
-
-
-To edit the docs locally, you need to clone this repository:
+## Getting Started
+1. Clone the repository with submodules:
```bash
-git clone --recurse-submodules --depth 1 https://github.com/jenkins-x/jx-docs.git
+git clone --recurse-submodules --depth 1 https://github.com/jenkins-x/jx-docs.git
+cd jx-docs
```
-#### Git submodules
+2. Install dependencies:
+```bash
+npm install
+```
-
+## Development Setup
-Notice the use of `--recurse-submodules` in the clone command above.
-This option will pull in two git [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), namely
-[docsy](https://github.com/google/docsy) and [labs-enhancements](https://github.com/jenkins-x/enhancements).
+### Git Submodules Management
-If you already have a git clone without the submodules checked out you can run:
+This repository uses two submodules:
+- [docsy](https://github.com/google/docsy) - Documentation theme
+- [labs-enhancements](https://github.com/jenkins-x/enhancements) - Jenkins X enhancements
+Common submodule operations:
```bash
+# Update submodules after fresh clone
git submodule update --init --recursive
-```
-In subsequent updates of the sources via `git pull` also remember to pull the changes from the submodules:
-
-```bash
+# Update submodules with latest changes
git pull --recurse-submodules
-```
-you can view the commit sha of the sub-modules via:
-
-```bash
+# Check submodule status
git submodule status --recursive
```
-### Downloading npm modules
-
-
+## Building the Documentation
-After getting all the sources, you need to [install npm](https://www.npmjs.com/get-npm) and make sure the required npm modules are installed:
+### Local Development
+1. Set required environment variable:
```bash
-npm install
+set HUGO_GH_ACCESS_TOKEN=
```
-### Running Hugo
-
-
-
-The site itself is built with [Hugo](https://gohugo.io/) and configured in [`config.toml`](./config.toml).
-You have two options to run Hugo, either directly on your machine or via [Docker Compose](https://github.com/docker/compose).
-The following two sections describe the two alternatives in more detail.
-
-**NOTE:** Hugo renders the site in memory in development mode.
-Per default, no content is written to disk.
-
-#### Locally
-
-
-
-If you want to build the site locally on your machine, you need to [install](https://gohugo.io/getting-started/installing) Hugo.
-Check the [Makefile](./Makfile) for the latest recommended version use and check whether the environment variables of Golang are set.
-Set the env variable HUGO_GH_ACCESS_TOKEN to a github token that can read from jenkins-x/jx repo to allow the contributors plugin to run.
-
-Once installed, you can run:
-
+2. Start Hugo server:
```bash
make server
```
+Access the site at [http://localhost:1313](http://localhost:1313)
-You can now access the site under [localhost:1313](http://localhost:1313).
-
-#### Dockerized
-
-
-
-Instead of installing Hugo locally, you can use the provided `docker-compose.yml` to spin up the Hugo server in a containerized environment.
-Make sure you have [Docker](https://docs.docker.com/install/) installed.
+### Docker Development
+1. Start the containerized environment:
```bash
make compose-up
```
-You can now access the site under [localhost:1313](http://localhost:1313).
-The Hugo server is running in the background.
-You can stop it via:
-
+2. Stop the environment:
```bash
make compose-down
```
+Access the site at [http://localhost:1313](http://localhost:1313)
-## Common Workflows
-
-
-
-### Running spell check
+## Development Tools
-
-
-We are not all masters of spelling, so luckily there are tools to help us fix that.
-We are using [node-markdown-spellcheck](https://github.com/lukeapage/node-markdown-spellcheck) to run through all our markdown files and list any spelling issue or unknown word.
-
-To make this as simple as possible, just run the following command:
+### Spell Checker
+Run spell check on markdown files:
```bash
make spellcheck
```
+Add new valid words to [.spelling](./.spelling) file (maintain alphabetical order).
-The report likely includes words that are spelt correctly, but that just means the spell checker is not aware of the correct spelling (happens a lot for technical terms, commands, etc.).
-Please edit [`.spelling`](./.spelling) and add the unknown word.
-Also, please try and keep the list alphabetically sorted, which makes it easier to navigate.
-
-### Checking links, images, etc
-
-
-
-To get help in checking all the links, we'll use [htmlproofer](https://github.com/chabad360/htmlproofer).
+### Link Checker
+Verify all links and images:
```bash
make linkcheck
```
+> Note: Initial run may be slow due to external link validation.
-**NOTE:** The initial run is really slow (due to external link checks) and that the cache is only build up when it finishes.
-
-**NOTE:**: It's safe to ignore the `... x509: certificate ...` errors for now
+## Content Management
-### Adding redirects
-
-
-
-If you move a page to a different location you can add a redirect via using an _aliases_ entry in the header of the page:
+### Page Redirects
+Add redirects for moved content using YAML front matter:
```yaml
aliases:
- - /some/old/path
- - /another/path
+ - /previous/path
+ - /old/path
```
-### Upgrading the enhancements content
-
-
-
-To upgrade to a new enhancements commit - we'll hopefully automate this soon!
+### Updating Content
+#### Upgrade Enhancements
```bash
cd content/en/docs/labs/enhancements
git checkout master
git pull
cd ..
git add enhancements
-git commit -m "move to latest enhancements"
+git commit -m "chore: update enhancements content"
```
-### Upgrading docsy
-
-Docsy is added to the jx-docs repository as a submodule under the themes directory.
-To update docsy, run the following commands:
-
+#### Upgrade Docsy Theme
```bash
cd themes/docsy
git pull origin master
git submodule update --init --recursive
```
-## Localization
+### Localization
-
+We welcome contributions in different languages. Please see language-specific guides:
+- [Chinese Documentation Guide](Localization_Chinese.md)
-To let more people know Jenkins X better, localization is essential and meaningful.
-And we should keep some rules about this, please read related languages below:
+## Contributing
-- [Chinese](Localization_Chinese.md)
+For detailed contribution guidelines, please refer to our [Documentation Contributing Guide](https://jenkins-x.io/community/documentation/).
-## Contributing
+---
-
+## Support
-Please refer to the documentation contributing guide available at [Jenkins X website](https://jenkins-x.io/community/documentation/).
+- [Jenkins X Website](https://jenkins-x.io)
+- [Community](https://jenkins-x.io/community/)