doc(website): partially adapt to SUSE style guide

website/docs/devel/i18n.md

@@ -10,18 +10,18 @@ languages and locales in software. This page describes how is that handled in Ag
 Each component need to solve this problem separately, see more details for each part in the details
 below.
 
-## Using Translations
+## Using translations
 
 Users have two ways how to change the used language in the Agama interface.
 
-### Language Selector
+### Language selector
 
 The sidebar of the web UI contains a component that allows to change the language. It was introduced
 in Agama 5 and it is the recommended way. The list of supported languages is read from the
 [languages.json](https://github.com/openSUSE/agama/blob/master/web/src/languages.json) file. Check
-the [The Web Frontend](#the-web-frontend) for further details.
+the [The web front-end](#the-web-front-end) for further details.
 
-### URL Query Parameter
+### URL query parameter
 
 When using a remote installation it is possible to set the used language via an URL query parameter.
 This is an expert option.
@@ -42,7 +42,7 @@ beginning.
 For translation process Agama uses [Weblate](https://weblate.org/) tool running at the
 [openSUSE](https://l10n.opensuse.org/) instance.
 
-## The Workflow
+## The workflow
 
 The basic translation workflow looks like this:
 
@@ -58,7 +58,7 @@ The basic translation workflow looks like this:
 6. The translations in the PO files are regularly copied to the main repository using pull requests
 7. The PO files are processed during build so the translations can be used later at runtime
 
-## Staging Translation Repository
+## Staging translation repository
 
 The special [agama-weblate](https://github.com/openSUSE/agama-weblate) repository works like a
 buffer between the Agama sources and the Weblate tool.
@@ -77,7 +77,7 @@ The content between the main [agama](https://github.com/openSUSE/agama) and the
 [agama-weblate](https://github.com/openSUSE/agama-weblate) GitHub repositories is synchronized
 automatically using the GitHub Actions.
 
-### Uploading Translatable Texts
+### Uploading translatable texts
 
 Collecting and uploading the translatable texts is done by the
 [weblate-update-pot.yml](https://github.com/openSUSE/agama/blob/master/.github/workflows/weblate-update-pot.yml)
@@ -94,7 +94,7 @@ action detail and use the "Run workflow" option at the top of the page.
 The code compares the old POT file with the new one and if there is no change besides the timestamps
 in the file it is not uploaded to `agama-weblate`.
 
-### Downloading Updated Translations
+### Downloading updated translations
 
 The translations from the `agama-weblate` repository are merged back by the
 [weblate-merge-po.yml](https://github.com/openSUSE/agama/blob/master/.github/workflows/weblate-merge-po.yml)
@@ -107,35 +107,35 @@ GitHub action.
 
 If there are no changes besides the timestamps in the PO files the pull request is not created.
 
-## Weblate Configuration
+## Weblate configuration
 
 The [Agama Weblate](https://l10n.opensuse.org/projects/agama/) project defines a separate
-translation component for each Agama part (the web frontend, the D-Bus backend and the command line
-interface).
+translation component for each Agama part (the web front-end, the D-Bus back-end and the command
+line interface).
 
 For reading the translations it uses the [agama-weblate](https://github.com/openSUSE/agama-weblate)
 GitHub repository, but for the source code locations it uses the original
 [agama](https://github.com/openSUSE/agama) repository. That means after clicking the source location
 link in the Weblate you will see the correct source location in the other repository.
 
-### Plugins
+### Plug-ins
 
 The Weblate components use the
 [msgmerge](https://docs.weblate.org/en/weblate-4.9.1/admin/addons.html#addon-weblate-gettext-msgmerge)
-plugin which automatically updates all PO files to match the POT file. That means after adding or
+plug-in which automatically updates all PO files to match the POT file. That means after adding or
 updating any translatable text the changes are automatically applied to all existing PO files and
 translators can translate the new or updated texts immediately.
 
-## Technical Details
+## Technical details
 
 This part describes technical and implementation details. It also describes the translation process
 for developers.
 
-### The Web Frontend
+### The web front-end
 
-Most of the translatable texts which can user see in Agama are defined in the web frontend. However,
-the web frontend can display some translated texts coming from the backend part so it is important
-to set the same language in both parts and make sure the translations are available there.
+Most of the translatable texts which can user see in Agama are defined in the web front-end.
+However, the web front-end can display some translated texts coming from the back-end part so it is
+important to set the same language in both parts and make sure the translations are available there.
 
 The list of supported languages is read from the
 [languages.json](https://github.com/openSUSE/agama/blob/master/web/src/languages.json). Such a list
@@ -160,7 +160,7 @@ If you need to manually update the `languages.json` file, run:
 web/share/update-languages.py > web/src/languages.json
 ```
 
-### Marking Texts for Translation
+### Marking texts for translation
 
 The texts are marked for translation using the usual functions like `_()`, `n_()` and others. It is
 similar to the GNU gettext style.
@@ -213,7 +213,7 @@ If you need to insert some values into the text you should use the [formatting
 function](#formatting-texts). It is recommended to use [translator comments](#translators-comments)
 for short or ambiguous texts.
 
-#### Plural Form
+#### Plural form
 
 If the translated text contains a number or quantity it is good to use a plural form so the
 translated texts looks naturally.
@@ -233,7 +233,7 @@ specific number. See more details about the [plural
 forms](https://www.gnu.org/software/gettext/manual/html_node/Plural-forms.html) in the GNU gettext
 documentation.
 
-#### Translating Constants
+#### Translating constants
 
 The top-level constants are evaluated too early, at that time the translations are not available yet
 and the language is not set.
@@ -253,7 +253,7 @@ export default function Foo() {
   <label>{_(LABELS[value])}</label>
 ```
 
-#### Formatting Texts
+#### Formatting texts
 
 For formatting complex texts use the C-like `sprintf()` function.
 
@@ -309,7 +309,7 @@ sprintf(_("Service is %s enabled"), msgNot);
 enabled ? _("Service is enabled") : _("Service is disabled");
 ```
 
-#### TRANSLATORS Comments
+#### TRANSLATORS comments
 
 You can use a special `TRANSLATORS` keyword in the comment preceding the text marked for
 translation. All comments after the keyword are included in the translations file, this should help
@@ -362,7 +362,7 @@ The translators can change the order of the arguments if needed using additional
 arguments. For example to change the order of the arguments in `"Foo %s %s"` they can translate it
 as `"Bar %2$s %1$s"`.
 
-### Missing Translations
+### Missing translations
 
 Here are some code examples which might look correct at the first sight. They even work, no crash.
 But there are still translation problems with them.
@@ -376,35 +376,35 @@ user)`).
 
 In both cases the strings will not be extracted to the POT file.
 
-### ESLint Plugin
+### ESLint plug-in
 
-There is special ESLint plugin
+There is special ESLint plug-in
 [eslint-plugin-agama-i18n](https://github.com/openSUSE/eslint-plugin-agama-i18n) which ensures that
 a string literal is passed to the translation functions. See more details there.
 
-### Testing Language
+### Testing language
 
 The Agama web interface supports special testing `xx` language. That language needs to be selected
 manually by adding the `?lang=xx` query string to the server URL. With this setting the `_()` and
 `n_()` translation functions replace all alphabetical characters by the `x` symbol.
 
 This can be used for testing to find out the texts which are not marked for translation. If a text
 is not replaced by the `x` symbols then either it is not marked for translation or it comes from the
-backend and it should be translated by the backend.
+back-end and it should be translated by the back-end.
 
 However, this is not perfect. It will replace also the texts mentioned in the [missing
 translations](#missing-translations) section above but in reality the there would be no translations
 available for them.
 
-### Building POT File
+### Building the POT file
 
 The translatable strings are extracted from the source files by using the standard `xgettext` tool.
 There is a helper script [build_pot](https://github.com/openSUSE/agama/blob/master/web/build_pot)
 which defines the needed parameters for the `xgettext` tool.
 
 To build the POT file locally just run the script, it will save the output to the `agama.pot` file.
 
-### Loading Web UI Translations
+### Loading web UI translations
 
 The translations are loaded by the `<script src="po.js" defer></script>` HTML code in the
 [index.html](https://github.com/openSUSE/agama/blob/master/web/src/index.html) file. But there is no
@@ -413,7 +413,7 @@ such file in Agama but one `po.<LANG>.js` file per language, like `po.cs.js`.
 The trick is that Agama's web server checks the `agamaLang` cookie sent in the HTTP request header
 and returns the content from the respective file.
 
-### Development Server
+### Development server
 
 Because Agama serves the `po.js` file a bit differently as described in the
 [](#loading-web-ui-translations) section above we need to implement this logic also in the
@@ -426,15 +426,15 @@ uses redirection because the built translation files are only available in the w
 the result is the same, the browser gets a different content according to the currently configured
 language.
 
-### Backend Locale
+### Back-end locale
 
 The Agama server exposes a `uiLocale` configuration option via the `/api/l10n/locales/config`
 endpoint which defines the locale used by all the services.
 
 The `uiLocale` property is a single global value shared by all connected clients. That means it is
 possible to use only one language for all clients, if more users connect to the server and uses a
 different UI language then there will be race conditions and the other users might see the texts
-coming from the backend in another language than expected.
+coming from the back-end in another language than expected.
 
 This is a known limitation, we expect that only one user at a time will access the Agama installer
 or if multiple users use the same server we expect that they will be from the same team or company
@@ -448,9 +448,9 @@ sudo busctl --address unix:path=/run/agama/bus get-property org.opensuse.Agama1
 /org/opensuse/Agama1/Locale org.opensuse.Agama1.Locale UILocale
 ```
 
-#### Backend Translations
+#### Back-end translations
 
-The backend might return texts from external components like `libstorage-ng`. Make sure the
+The back-end might return texts from external components like `libstorage-ng`. Make sure the
 translations for those components are also available for Agama, e.g. the `libstorage-ng`
 translations are stored in the `libstorage-ng-lang` package or the YaST translations are stored in
 `yast2-trans-<LANG>` packages.
@@ -461,8 +461,8 @@ Here are some hints what to do when some untranslated text appears in the Agama
 
 1. Check that the text is marked for translation, for a quick verification you might try setting the
    [testing language](#testing-language).
-2. If the text comes from backend or the other parts check that the appropriate [language
-   package](#backend-translations) is installed.
+2. If the text comes from back-end or the other parts check that the appropriate [language
+   package](#back-end-translations) is installed.
 3. The text should be [extracted into the POT file](#building-pot-file)
 4. The [agama.pot](https://github.com/openSUSE/agama-weblate/blob/master/web/agama.pot) in the
    `agama-weblate` repository is up to date, if not then run the [Weblate Update
@@ -483,4 +483,4 @@ Here are some hints what to do when some untranslated text appears in the Agama
 10. Check the current language used in the browser, run `agama.language` command in the development
     tools console, check the `agamaLang` cookie value (run `document.cookie` command in the
     console).
-11. Check the language used by the [Backend Locale](#backend-locale).
+11. Check the language used by the [Back-end locale](#back-end-locale).

website/docs/devel/packaging.md

@@ -15,14 +15,14 @@ While the Ruby-based one (`rubygem-agama-yast`) is built as any other YaST packa
 (`agama`), the CLI (`agama-cli`), and the web UI (`agama-web-ui`) rely on [OBS source
 services](https://openbuildservice.org/help/manuals/obs-user-guide/cha.obs.source_service.html).
 
-## Versioning Policy
+## Versioning policy
 
 We have decided to follow a single number schema: 1, 2, 3, etc. However, if we need to release a
 hot-fix, we might use a dotted version (e.g., 2.1). Moreover, all the components share the same
 version number. Releasing a new version implies that all of them get the new number, no matter if
 they contain changes or not.
 
-## Bumping the Version
+## Bumping the version
 
 In order to release a new version, we need to:
 
@@ -47,7 +47,7 @@ After creating the tag on the server the GitHub Actions will publish the package
 [systemsmanagement:Agama:Devel](https://build.opensuse.org/project/show/systemsmanagement:Agama:Devel)
 project and create submit requests to openSUSE Factory.
 
-## Building the Packages
+## Building the packages
 
 The packages are updated automatically using the GitHub actions. Here are details for manual update.
 
@@ -104,7 +104,7 @@ the latest commit respect such a tag. (e.g. `2.1+42`).
 You can read more about the overall approach of this package in the following article:
 [Git work flows in the upcoming 2.7 release](https://openbuildservice.org/2016/04/08/new_git_in_27/).
 
-### The Live ISO
+### The live ISO
 
 The ISO for openSUSE products is built in the
 [systemsmanagement:Agama:Devel/agama-installer-openSUSE](https://build.opensuse.org/package/show/systemsmanagement:Agama:Devel/agama-installer-openSUSE)

website/docs/devel/yupdate.md

@@ -27,7 +27,7 @@ yupdate patch openSUSE/agama master
 
 You can replace the `master` branch with any branch containing a fix or a new feature.
 
-## Patching from a Local Git Checkout
+## Patching from a local Git checkout
 
 First you need to run the `rake server` command in your Agama Git checkout.
 
@@ -56,10 +56,11 @@ You can modify the update process with these environment variables:
 - `NODE_ENV=development` - The web front-end will be built in the development mode. The files will
   not be minimized and additional `*.map` files will be generated. This helps with debugging in the
   browser, you can get the locations in the original source files.
-- `YUPDATE_SKIP_FRONTEND=1` - Skip updating the web frontend. Use this option when you use the
-  webpack development server for running the web frontend. In that case updating the web frontend does
-  not make sense because it is running in a different server. This saves some time and disk/RAM space.
-- `YUPDATE_SKIP_BACKEND=1` - Skip updating the D-Bus service backend. This is similar to the
+- `YUPDATE_SKIP_FRONTEND=1` - Skip updating the web front-end. Use this option when you use the
+  webpack development server for running the web front-end. In that case updating the web front-end
+  does not make sense because it is running in a different server. This saves some time and disk/RAM
+  space.
+- `YUPDATE_SKIP_BACKEND=1` - Skip updating the D-Bus service back-end. This is similar to the
   previous option, use it when you do want to keep the D-Bus service unchanged.
 
 ## Notes
@@ -74,12 +75,12 @@ system becomes completely frozen and might not respond to any input event.
 Currently the minimum for a safe operation is around 4GB RAM. If you use the `NPM_CACHE=1` option
 then recommended minimum is around 5GB.
 
-## Activating the Changes
+## Activating the changes
 
 After patching the files the DBus service is restarted if any related file has been changed. That
 means the configured settings will be lost.
 
-To activate the changes in the web frontend you need to reload the page in the browser.
+To activate the changes in the web front-end you need to reload the page in the browser.
 
 :::warning
 _In the Firefox browser you need to use the `Ctrl+F5` combination for reloading the page,
@@ -90,13 +91,13 @@ update on the server!_
 In some special cases you might need to do some additional actions manually, the update script might
 not handle all corner cases.
 
-## Implementation Details
+## Implementation details
 
 The support is implemented in the main
 [Rakefile](https://github.com/openSUSE/agama/blob/master/Rakefile) and in the
 [.yupdate.pre](https://github.com/openSUSE/agama/blob/master/.yupdate.pre) and
 [.yupdate.post](https://github.com/openSUSE/agama/blob/master/.yupdate.post) hook scripts.
 
 - The `.yupdate.pre` script prepares the system for compiling and installing new Agama files.
-- The `Rakefile` code builds and installs both backend and frontend parts.
-- The `.yupdate.pre` script activates the changes, it restarts the backend if needed.
+- The `Rakefile` code builds and installs both back-end and front-end parts.
+- The `.yupdate.pre` script activates the changes, it restarts the back-end if needed.

website/docs/index.md

@@ -2,7 +2,7 @@
 sidebar_position: 1
 ---
 
-# About
+# Agama's documentation
 
 This section covers a wide range of Agama-related topics. To make it easy to find the information
 you are looking for, the documentation is organized in two different parts, depending on your

website/docs/user/autoyast.md

@@ -1,4 +1,4 @@
-# AutoYaST Support
+# AutoYaST support
 
 Agama offers a mechanism to perform [unattended installations](./unattended). However, we
 would like AutoYaST users to be able to use their profiles in Agama. This document describes how