docs: update structure and titles (SAP#9338)

* docs: update structure and titles * chore: update * chore: fix links to migration guide
dobrinyonkov · Jun 30, 2024 · 4d685f3 · 4d685f3
1 parent 43d5720
commit 4d685f3
Show file tree

Hide file tree

Showing 34 changed files with 97 additions and 249 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,5 @@
-![UI5 icon](/docs/images/UI5_logo_wide.png)
+#  ![UI5 icon](https://raw.githubusercontent.com/SAP/ui5-webcomponents/main/docs/images/UI5_logo_water.png)UI5 Web Components
 
-# UI5 Web Components
 [![CI](https://github.com/SAP/ui5-webcomponents/actions/workflows/test.yaml/badge.svg)](https://github.com/SAP/ui5-webcomponents/actions/workflows/test.yaml)
 [![npm Package Version](https://badge.fury.io/js/%40ui5%2Fwebcomponents.svg)](https://www.npmjs.com/package/@ui5/webcomponents)
 [![REUSE status](https://api.reuse.software/badge/github.com/SAP/ui5-webcomponents)](https://api.reuse.software/info/github.com/SAP/ui5-webcomponents)

diff --git a/docs/Release Management.md → docs/08-Releases.md b/docs/Release Management.md → docs/08-Releases.md
@@ -1,4 +1,4 @@
-# Release Management
+# Releases
 
 The article describes the release process management of UI5 Web Components.
 

diff --git a/docs/FAQ.md → docs/09-FAQ.md b/docs/FAQ.md → docs/09-FAQ.md
@@ -1,3 +1,7 @@
+---
+sidebar_label: FAQ
+---
+
 # Frequently Asked Questions
 
 **Q: How can I play with UI5 Web Components easily?**

diff --git a/docs/4-frameworks/01-React.md b/docs/4-frameworks/01-React.md
@@ -1,4 +1,4 @@
-# Get Started with UI5 Web Components & React
+# UI5 Web Components & React
 
 In this tutorial, you will learn how to add UI5 Web Components to your application. You can add UI5 Web Components both to new React applications and to already existing ones.
 

diff --git a/docs/4-frameworks/02-Angular.md b/docs/4-frameworks/02-Angular.md
@@ -1,4 +1,4 @@
-# Get Started with UI5 Web Components & Angular
+# UI5 Web Components & Angular
 
 In this tutorial, you will learn how to use `UI5 Web Components` in an Angular application. In the second part, we will introduce `UI5 Web Components for Angular` - wrapper library for UI5 Web Components, improving their integration with Angular.
 

diff --git a/docs/4-frameworks/03-Vue.md b/docs/4-frameworks/03-Vue.md
@@ -1,4 +1,4 @@
-# Get Started with UI5 Web Components & Vue.js
+# UI5 Web Components & Vue.js
 
 In this tutorial you will learn how to add UI5 Web Components to your application. You can add UI5 Web Components both to new Vue.js applications and to already existing ones.
 

diff --git a/docs/5-development/README.md b/docs/5-development/README.md
@@ -1,3 +1,3 @@
-# UI5 Web Components Custom Development
+# UI5 Web Components Development
 
 This section explains how to create your own custom UI5 Web Components packages and develop your own UI5 Web Components.
diff --git a/docs/6-contributing/01-development-workflow.md b/docs/6-contributing/01-development-workflow.md
@@ -1,6 +1,6 @@
-# General Development Workflow
-This document aims to explain the steps component developers would have to perform
-on daily basis from forking the project to merging a change, emphasising on the Github workflow.
+# Development Workflow
+
+This article explains the daily development workflow for component developers: from forking to merging changes.
 
 
 ## 1. Fork the UI5 Web Components repository.

diff --git a/docs/6-contributing/02-conventions-and-guidelines.md b/docs/6-contributing/02-conventions-and-guidelines.md
@@ -1,4 +1,5 @@
-# Development Conventions and Guidelines
+# Conventions and Guidelines
+
 ## JavaScript Coding Guidelines
 We enforce code style rules using [ESLint](https://eslint.org). Execute `npm run lint` to check your code for style issues.  
 You may also find an ESLint integration for your favorite IDE [here](https://eslint.org/docs/user-guide/integrations).

diff --git a/docs/DoD.md → docs/6-contributing/03-DoD.md b/docs/DoD.md → docs/6-contributing/03-DoD.md
diff --git a/docs/6-contributing/03-website.md b/docs/6-contributing/03-website.md
diff --git a/docs/6-contributing/04-website-samples.md → docs/6-contributing/04-website.md b/docs/6-contributing/04-website-samples.md → docs/6-contributing/04-website.md
@@ -1,3 +1,22 @@
+# Running the Website
+
+The UI5 Web Components Website app is the entry point of the UI5 Web Components project. 
+The app includes documentation, API reference and samples for all the available web components.
+
+The website can be run locally to test your changes and samples.
+In order to do so, you have to follow the steps below:
+
+In your terminal, run the following commands:
+
+```bash
+yarn
+yarn start:website
+```
+
+This will build all the necessary assets and will start local server on your machine
+and finally open the website in your browser.
+
+
 # Creating Website Samples
 
 The website app is developed in its own package `packages/website`. Components features or states are demonstrated via samples meant for consumers.

diff --git a/docs/6-contributing/05-storybook.md b/docs/6-contributing/05-storybook.md
diff --git a/docs/6-contributing/06-storybook-samples.md b/docs/6-contributing/06-storybook-samples.md
diff --git a/docs/6-contributing/README.md b/docs/6-contributing/README.md
@@ -1,5 +1,5 @@
-# Contributing to the UI5 Web Components Project
+# Contributing 
 
-Contributions are welcome!
+Contributions to the UI5 Web Components project are welcome!
 
 This section explains our conventions, how to run the project locally, and more.
diff --git a/docs/Migrating to version 2.0 guide.md → docs/7-migration-guides/01-to-version-2.md b/docs/Migrating to version 2.0 guide.md → docs/7-migration-guides/01-to-version-2.md
@@ -1,6 +1,10 @@
-# UI5 Web Components 2.0 migration guide
+---
+sidebar_label: To UI5 Web Components 2.0
+---
 
-This documentation will assist you in seamlessly transitioning from UI5 Web Components v1.x to the latest version, UI5 Web Components 2.0.
+# Migration to UI5 Web Components 2.0
+
+This guide will assist you in seamlessly transitioning from UI5 Web Components version 1.x to UI5 Web Components 2.0.
 
 ## @ui5/webcomponents-base
 

diff --git a/docs/7-migration-guides/README.md b/docs/7-migration-guides/README.md
@@ -0,0 +1,5 @@
+# Migration Guides
+
+UI5 Web Components versioning is based on [Semantic Versioning](https://semver.org/).
+
+Breaking changes are only released on major version upgrades, and thoroughly documented in the following upgrade guides.
diff --git a/docs/README.md b/docs/README.md
@@ -1,5 +1,38 @@
-# UI5 Web Components Documentation
+# Introduction
 
-Welcome to the UI5 Web Components documentation!
+The UI5 Web Components project offers a rich set of enterprise-grade, reusable UI elements built on top of the [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) standards.
+With UI5 Web Components, developers can leverage a powerful, flexible, and future-proof toolkit to create anything from **static web sites** to **complex web applications**.
 
-Browse the directories to find the needed content, or read the same docs on the [official site](https://sap.github.io/ui5-webcomponents/play)
+
+## Key Features of UI5 Web Components
+
+- Enterprise-Grade: A comprehensive collection of reusable UI elements that adhere to enterprise standards - accessibility, themeability, i18n and more.
+
+- Framework Agnostic: Fully compatible with any current or future web development frameworks such as React, Angular, and Vue, allowing seamless integration into any tech stack.
+
+- Elegant: Being custom HTML elements, they hide implementation complexity behind a single HTML tag, making them easily usable with the standard DOM APIs.
+
+- Consistent User Experience: Implementing the [SAP Fiori design](https://experience.sap.com/fiori-design/) and adhering to the [SAP Fiori Design Guidelines](https://experience.sap.com/fiori-design-web/) ensures a consistent and intuitive user experience across all applications.
+
+- Open Source: UI5 Web Components is an open-source project available to the general public, inviting developers from all backgrounds to contribute and benefit.
+
+- SAP Backing: Developed and maintained by [SAP](https://sap.com) as part of the [UI5](https://openui5.org/) product family, guaranteeing ongoing support and integration with SAP's ecosystem.
+
+
+## Ecosystem
+
+UI5 Web Components are complemented by a range of related projects that enhance the development experience even further. These projects build on top of the core UI5 Web Components, providing additional functionalities and integrations tailored to specific frameworks and use cases.
+
+### UI5 Web Components for React
+
+[UI5 Web Components for React](https://github.com/SAP/ui5-webcomponents-react) is a wrapper implementation around UI5 Web Components which makes using them in React even more comfortable. The current version of React (`react 18`) has some shortcomings when it comes to handling Custom Elements, namely the binding of `boolean` attributes as well as adding event listeners to custom event names like `selection-change`. With the help of UI5 Web Components for React, you can use the UI5 Web Components in React as if they were native React components. In addition to that, this library is also offering some complex layout components built on top of UI5 Web Components as well as Charting Components.
+
+**Note:** [React 19](https://react.dev/blog/2024/04/25/react-19) promises to fill all gaps in the web coponents support - the binding of `boolean` attributes and subscribing to custom events.
+
+### UI5 Web Components for Angular
+
+[UI5 Web Components for Angular](https://github.com/SAP/ui5-webcomponents-ngx) is a wrapper implementation around UI5 Web Components which to make it work with Angular without needing to use the `CUSTOM_ELEMENTS_SCHEMA` or `NO_ERRORS_SCHEMA` schemas.
+Moreover, all Angular-specific features, such as two-way data binding and Angular Form support, work out of the box.
+
+
+**Continue reading to start using UI5 Web Components right away!**
diff --git a/docs/images/UI5_logo_water.png b/docs/images/UI5_logo_water.png
diff --git a/docs/images/UI5_logo_wide.png b/docs/images/UI5_logo_wide.png
diff --git a/packages/ai/README.md b/packages/ai/README.md
@@ -1,7 +1,4 @@
-![UI5 icon](https://raw.githubusercontent.com/SAP/ui5-webcomponents/main/docs/images/UI5_logo_wide.png)
-
-
-# UI5 Web Components - AI
+#  ![UI5 icon](https://raw.githubusercontent.com/SAP/ui5-webcomponents/main/docs/images/UI5_logo_water.png)UI5 Web Components - AI
 
 [![npm Package Version](https://badge.fury.io/js/%40ui5%2Fwebcomponents.svg)](https://www.npmjs.com/package/@ui5/webcomponents)
 

diff --git a/packages/base/README.md b/packages/base/README.md
@@ -1,7 +1,4 @@
-![UI5 icon](https://raw.githubusercontent.com/SAP/ui5-webcomponents/main/docs/images/UI5_logo_wide.png)
-
-
-# UI5 Web Components - Base
+# ![UI5 icon](https://raw.githubusercontent.com/SAP/ui5-webcomponents/main/docs/images/UI5_logo_water.png)UI5 Web Components - Base
 
 [![npm Package Version](https://badge.fury.io/js/%40ui5%2Fwebcomponents.svg)](https://www.npmjs.com/package/@ui5/webcomponents)
 

diff --git a/packages/compat/README.md b/packages/compat/README.md
@@ -1,7 +1,4 @@
-![UI5 icon](https://raw.githubusercontent.com/SAP/ui5-webcomponents/main/docs/images/UI5_logo_wide.png)
-
-
-# UI5 Web Components - Compatibility
+# ![UI5 icon](https://raw.githubusercontent.com/SAP/ui5-webcomponents/main/docs/images/UI5_logo_water.png)UI5 Web Components - Compatibility
 
 [![npm Package Version](https://badge.fury.io/js/%40ui5%2Fwebcomponents.svg)](https://www.npmjs.com/package/@ui5/webcomponents)
 

diff --git a/packages/create-package/README.md b/packages/create-package/README.md
@@ -1,7 +1,4 @@
-![UI5 icon](https://raw.githubusercontent.com/SAP/ui5-webcomponents/main/docs/images/UI5_logo_wide.png)
-
-
-# UI5 Web Components - Create Package
+# ![UI5 icon](https://raw.githubusercontent.com/SAP/ui5-webcomponents/main/docs/images/UI5_logo_water.png)UI5 Web Components - Create Package
 
 [![npm Package Version](https://badge.fury.io/js/%40ui5%2Fwebcomponents.svg)](https://www.npmjs.com/package/@ui5/webcomponents)
 

diff --git a/packages/fiori/README.md b/packages/fiori/README.md
@@ -1,7 +1,4 @@
-![UI5 icon](https://raw.githubusercontent.com/SAP/ui5-webcomponents/main/docs/images/UI5_logo_wide.png)
-
-
-# UI5 Web Components - Fiori
+# ![UI5 icon](https://raw.githubusercontent.com/SAP/ui5-webcomponents/main/docs/images/UI5_logo_water.png)UI5 Web Components - Fiori
 
 [![npm Package Version](https://badge.fury.io/js/%40ui5%2Fwebcomponents.svg)](https://www.npmjs.com/package/@ui5/webcomponents)
 

diff --git a/packages/icons-business-suite/README.md b/packages/icons-business-suite/README.md
@@ -1,7 +1,4 @@
-![UI5 icon](https://raw.githubusercontent.com/SAP/ui5-webcomponents/main/docs/images/UI5_logo_wide.png)
-
-
-# UI5 Web Components - SAP Business Suite Icons
+# ![UI5 icon](https://raw.githubusercontent.com/SAP/ui5-webcomponents/main/docs/images/UI5_logo_water.png)UI5 Web Components - SAP Business Suite Icons
 
 [![npm Package Version](https://badge.fury.io/js/%40ui5%2Fwebcomponents.svg)](https://www.npmjs.com/package/@ui5/webcomponents)