Reduce main readme to bare instructions only

DOCUMENTATION.md

@@ -0,0 +1,107 @@
+# Armbian Documentation
+
+[![Create offline documentation to release](https://github.com/armbian/documentation/actions/workflows/release.yaml/badge.svg)](https://github.com/armbian/documentation/actions/workflows/release.yaml)
+
+<p align="center">
+  <a target="_blank" href="https://docs.armbian.com">
+    <img alt="logo" src="./docs/images/logo.png">
+  </a>
+</p>
+
+## Overview
+
+Documentation is written in [markdown](https://www.markdownguide.org/basic-syntax/) and stored in the `docs/` subfolder.  Images go in `docs/images`.
+
+This repo is meant for storing and quick glances.  Official output is [https://docs.armbian.com](https://docs.armbian.com).
+
+Armbian Documentation is available in the following formats:
+
+* [Official document website](https://docs.armbian.com),
+* [PDF document](https://github.com/armbian/documentation/releases/latest)
+
+## Contributing
+
+This site is built with [mkdocs](https://github.com/mkdocs/mkdocs/) and depends on [mkdocs-material](https://github.com/squidfunk/mkdocs-material).
+
+Armbian Documentation naming of document files follows this rules:
+
+`[Parent-Topic-Example]_[Child-Topic]-example.md`
+
+`Parent-Topic-Name` and `Child-Topic-Name` are separated by an underscore `_`.  Hyphens `-` are automatically converted to space.
+
+Please try to avoid creating new parent topics unless absolutely necessary.
+
+Current Parent Topics:
+
+* User Guide
+* Hardware notes
+* Developer Guide
+* Contributor Process
+* Release management
+* Community
+
+See the [document template](.github/DOCUMENT_TEMPLATE.md) before you writing any content.
+
+## Working on the content
+
+### Prerequisites
+
+Ensure you have Python and the necessary development packages installed:
+
+```bash
+sudo apt-get update
+sudo apt-get install python3 python3-pip python3-venv python3.11-dev
+```
+
+If using Debian, you may need to install the following packages for `mkdocs-material`:
+
+```bash
+sudo apt-get install libcairo2 pango1.0-tools
+```
+
+### Cloning the Repository
+
+Next, clone the Armbian documentation repository:
+
+```bash
+git clone https://github.com/armbian/documentation
+cd documentation
+```
+
+### Setting Up the Environment
+
+Set up a Python virtual environment to isolate the project dependencies:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --use-pep517 -r requirements.txt
+```
+
+### Building and Serving the Documentation
+
+To build and serve the documentation locally, allowing you to make edits and observe the results in real time, use:
+
+```bash
+mkdocs build --clean
+mkdocs serve -a 0.0.0.0:8000
+```
+
+You will be able to make edits to existing files and observe the results in real time.
+
+## Generate tools
+After adding a new file, either hand-edit `mkdocs.yml`, or re-run `tools/mkArmbianDocs.py` **unless making changes to the structure of the `docs/` folder**. (See below)
+
+### mkArmbianDocs.py
+Generate `mkdocs.yml` based on the contents of `docs/` folder
+
+* Command-line options for input and output directories
+* Requires install requirement
+* You don't need to run it every time unless making changes to the structure of the `docs/` folder
+* See `mkArmbianDocs.py -h` for help
+
+From the parent folder of the repo, run:
+
+`python3 tools/mkArmbianDocs.py && mkdocs build`
+
+This will generate the `mkdocs.yml` and publish built HTML to the `site/` folder.

README.md

@@ -1,107 +1,30 @@
-# Armbian Documentation
-
-[![Create offline documentation to release](https://github.com/armbian/documentation/actions/workflows/release.yaml/badge.svg)](https://github.com/armbian/documentation/actions/workflows/release.yaml)
-
 <p align="center">
   <a target="_blank" href="https://docs.armbian.com">
-    <img alt="logo" src="./docs/images/logo.png">
-  </a>
+    <img alt="logo" src="./docs/images/logo.png" width=128>
+  </a><br>
+  <strong>Armbian Documentation</strong><br>
+<br>
+<a href=https://github.com/armbian/documentation/actions/workflows/pdf-at-pr.yaml><img alt="GitHub Workflow Status" src="https://img.shields.io/github/actions/workflow/status/armbian/documentation/pdf-at-pr.yaml?logo=githubactions&label=HTML%20page&style=for-the-badge&branch=main"></a>
 </p>
 
-## Overview
-
-Documentation is written in [markdown](https://www.markdownguide.org/basic-syntax/) and stored in the `docs/` subfolder.  Images go in `docs/images`.
-
-This repo is meant for storing and quick glances.  Official output is [https://docs.armbian.com](https://docs.armbian.com).
-
-Armbian Documentation is available in the following formats:
-
-* [Official document website](https://docs.armbian.com),
-* [PDF document](https://github.com/armbian/documentation/releases/latest)
-
-## Contributing
-
-This site is built with [mkdocs](https://github.com/mkdocs/mkdocs/) and depends on [mkdocs-material](https://github.com/squidfunk/mkdocs-material).
-
-Armbian Documentation naming of document files follows this rules:
-
-`[Parent-Topic-Example]_[Child-Topic]-example.md`
-
-`Parent-Topic-Name` and `Child-Topic-Name` are separated by an underscore `_`.  Hyphens `-` are automatically converted to space.
-
-Please try to avoid creating new parent topics unless absolutely necessary.
-
-Current Parent Topics:
-
-* User Guide
-* Hardware notes
-* Developer Guide
-* Contributor Process
-* Release management
-* Community
-
-See the [document template](.github/DOCUMENT_TEMPLATE.md) before you writing any content.
-
-## Working on the content
-
-### Prerequisites
-
-Ensure you have Python and the necessary development packages installed:
-
-```bash
-sudo apt-get update
-sudo apt-get install python3 python3-pip python3-venv python3.11-dev
-```
-
-If using Debian, you may need to install the following packages for `mkdocs-material`:
-
-```bash
-sudo apt-get install libcairo2 pango1.0-tools
-```
-
-### Cloning the Repository
-
-Next, clone the Armbian documentation repository:
-
-```bash
-git clone https://github.com/armbian/documentation
-cd documentation
-```
-
-### Setting Up the Environment
-
-Set up a Python virtual environment to isolate the project dependencies:
-
-```bash
-python3 -m venv .venv
-source .venv/bin/activate
-pip install --use-pep517 -r requirements.txt
-```
-
-### Building and Serving the Documentation
-
-To build and serve the documentation locally, allowing you to make edits and observe the results in real time, use:
-
-```bash
-mkdocs build --clean
-mkdocs serve -a 0.0.0.0:8000
-```
+# Editing
 
-You will be able to make edits to existing files and observe the results in real time.
+### Online
 
-## Generate tools
-After adding a new file, either hand-edit `mkdocs.yml`, or re-run `tools/mkArmbianDocs.py` **unless making changes to the structure of the `docs/` folder**. (See below)
+Documentation edition goes in five simple steps.
 
-### mkArmbianDocs.py
-Generate `mkdocs.yml` based on the contents of `docs/` folder
+|Step|Description|Visuals|
+|:-------:|---|---:|
+| 1. | Open <a href=https://docs.armbian.com/ target="_blank">website</a> and **find content you want to change**.| <details><summary>Expand</summary><a href=#><img alt="logo" src="./docs/images/edit-icon.png"></a></details> |
+| 2. | When you are done with editing, **Commit changes**. | <details><summary>Expand</summary><a href=#><img alt="logo" src="./docs/images/commit-changes.png"></a></details> |
+| 3. | Enter title and description of changes you are proposing. Proceed with **Propose changes** | <details><summary>Expand</summary><a href=#><img alt="logo" src="./docs/images/propose-changes.png"></a></details> |
+| 4. | Following by **Create a pull request**. |<details><summary>Expand</summary><a href=#><img alt="logo" src="./docs/images/create-pull-reqest.png"></a></details> |
+| 5. | Verify your changes on **HTML rendered preview** at your pull reqest. |<details><summary>Expand</summary><a href=#><img alt="logo" src="./docs/images/wait-for-preview.png"></a></details> |
 
-* Command-line options for input and output directories
-* Requires install requirement
-* You don't need to run it every time unless making changes to the structure of the `docs/` folder
-* See `mkArmbianDocs.py -h` for help
+### Offline
 
-From the parent folder of the repo, run:
+Please reffer to [those instructions](/DOCUMENTATION.md)
 
-`python3 tools/mkArmbianDocs.py && mkdocs build`
+### Tips 
 
-This will generate the `mkdocs.yml` and publish built HTML to the `site/` folder.
+<https://squidfunk.github.io/mkdocs-material/reference/>