opf · as-op · Aug 29, 2024 · Aug 29, 2024
diff --git a/docs/README.md b/docs/README.md
@@ -39,7 +39,7 @@ Please see our [Use Cases section](./use-cases/) for detailed how-to guides and
 
 ## Development
 
-* [Full development environment for developers on Ubuntu](./development/development-environment-ubuntu) and [Mac OS X](./development/development-environment-osx)
+* [Full development environment for developers](./development/development-environment)
 * [Developing plugins](./development/create-openproject-plugin)
 * [Developing OmniAuth Plugins](./development/create-omniauth-plugin)
 * [Running tests](./development/running-tests)

diff --git a/docs/development/README.md b/docs/development/README.md
@@ -96,10 +96,7 @@ If you want to contribute to OpenProject, please make sure to accept our Contrib
 
 ## Additional resources
 
-* [Development environment for Ubuntu 18.04](development-environment-ubuntu)
-* [Development environment for Mac OS X](development-environment-osx)
-* [Development environment using docker](development-environment-docker)
-
+* [Development environment](development-environment)
 * [Developing Plugins](create-openproject-plugin)
 * [Running Tests](running-tests)
 * [API Documentation](../api)

diff --git a/docs/development/concepts/README.md b/docs/development/concepts/README.md
@@ -12,14 +12,14 @@ This guide will introduce some concepts and give you a big picture of the develo
 
 Please choose an area that you would like to read about:
 
-| Topic                                                | Content                                                                       |
-|------------------------------------------------------|:------------------------------------------------------------------------------|
-| [Application architecture](application-architecture) | An introduction of the application architecture used at OpenProject.          |
-| [State management](state-management)                 | How does the frontend handle state and react to changes?                      |
-| [HAL resources](hal-resources)                       | What are HAL resources and how are they used in the frontend?                 |
-| [Permissions](permissions)                           | How are roles and permissions handled in OpenProject code?                    |
-| [Translations](translations)                         | How are translations used and built?                                          |
-| [Resource schemas](resource-schemas)                 | What is a schema and how is it tied to an editable resource?                  |
-| [Resource changesets](resource-changesets)           | How is change tracked to resources in the frontend? How to save the changes.  |
-| [Inline editing](inline-editing)                     | How does inline editing and the edit field functionality work in OpenProject? |
-| [Queries and QuerySpace](queries)                    | What is the Query API concept and how is it used in the frontend?             |
+| Topic                                                   | Content                                                                       |
+|---------------------------------------------------------|:------------------------------------------------------------------------------|
+| [Application architecture](../application-architecture) | An introduction of the application architecture used at OpenProject.          |
+| [State management](state-management)                    | How does the frontend handle state and react to changes?                      |
+| [HAL resources](hal-resources)                          | What are HAL resources and how are they used in the frontend?                 |
+| [Permissions](permissions)                              | How are roles and permissions handled in OpenProject code?                    |
+| [Translations](translations)                            | How are translations used and built?                                          |
+| [Resource schemas](resource-schemas)                    | What is a schema and how is it tied to an editable resource?                  |
+| [Resource changesets](resource-changesets)              | How is change tracked to resources in the frontend? How to save the changes.  |
+| [Inline editing](inline-editing)                        | How does inline editing and the edit field functionality work in OpenProject? |
+| [Queries and QuerySpace](queries)                       | What is the Query API concept and how is it used in the frontend?             |
diff --git a/docs/development/concepts/application-architecture/README.md b/docs/development/concepts/application-architecture/README.md
diff --git a/docs/development/create-openproject-plugin/README.md b/docs/development/create-openproject-plugin/README.md
@@ -136,7 +136,7 @@ It is probably best to use READMEs of already released plugins as a template.
     Activity, Issue Tracking, Time Tracking, Forums, and Backlogs are default.
     Also, the My Project Page should only show Project Description and Tickets blocks.
 3. Create a news article about the newly released plugin and its features.
-4. Twitter with a link to the news article.
+4. Share a link to the news article on social media.
 5. If the plugin is referenced in our feature tour, add a download link to the plugin in the feature tour
 
 ## Frontend plugins [WIP]

diff --git a/docs/development/development-environment/README.md b/docs/development/development-environment/README.md
@@ -0,0 +1,34 @@
+---
+sidebar_navigation:
+  title: Development setup
+description: OpenProject development setup
+keywords: development setup
+---
+
+# OpenProject development setup
+
+| OS/Method                          | Description                                                                       |
+|------------------------------------|-----------------------------------------------------------------------------------|
+| [Ubuntu / Debian](linux)           | Develop setup on Linux                                                            |
+| [via docker](docker)               | The quickest way to get started developing OpenProject is to use the docker setup |
+| [via docker (MacOS)](docker-macos) | MacOS specific docker topics                                                      |
+| [MacOS](macos)                     | Develop setup on MacOS                                                            |
+
+
+### Start Coding
+
+Please have a look at [our development guidelines](../code-review-guidelines/) for tips and guides on how to start
+coding. We have advice on how to get your changes back into the OpenProject core as smooth as possible.
+Also, take a look at the `doc` directory in our sources, especially
+the [how to run tests](../running-tests) documentation (we like to have automated tests for every new developed feature).
+
+### Troubleshooting
+
+The OpenProject logfile can be found in `log/development.log`.
+
+If an error occurs, it should be logged there (as well as in the output to STDOUT/STDERR of the rails server process).
+
+### Questions, Comments, and Feedback
+
+If you have any further questions, comments, feedback, or an idea to enhance this guide, please tell us at the
+appropriate [forum](https://community.openproject.org/projects/openproject/boards/9).
diff --git a/...opment-environment-docker-macos/README.md → ...opment-environment/docker-macos/README.md b/...opment-environment-docker-macos/README.md → ...opment-environment/docker-macos/README.md
@@ -1,13 +1,14 @@
 ---
 sidebar_navigation:
   title: Development setup via docker on MacOS
+  short_title: Setup via Docker on MacOS
 description: OpenProject development setup via docker on MacOS
 keywords: development setup docker macos
 ---
 
 # OpenProject development setup via docker (MacOS)
 
-This guide covers observed nuances with the docker runtime on MacOS. Please ensure you've gone through the general [OpenProject development setup via docker](../development-environment-docker) guide before proceeding.
+This guide covers observed nuances with the docker runtime on MacOS. Please ensure you've gone through the general [OpenProject development setup via docker](../docker) guide before proceeding.
 
 ## Docker on MacOS File System Performance
 

diff --git a/.../development-environment-docker/README.md → .../development-environment/docker/README.md b/.../development-environment-docker/README.md → .../development-environment/docker/README.md
@@ -1,6 +1,7 @@
 ---
 sidebar_navigation:
   title: Development setup via docker
+  short_title: Setup via Docker
 description: OpenProject development setup via docker
 keywords: development setup docker
 ---
@@ -464,7 +465,7 @@ Once the keycloak service is started and running, you can access the keycloak in
 and login with initial username and password as `admin`.
 
 Keycloak being an OpenID connect provider, we need to setup an OIDC integration for OpenProject.
-[Setup OIDC (keycloak) integration for OpenProject](../../installation-and-operations/misc/custom-openid-connect-providers/#keycloak)
+[Setup OIDC (keycloak) integration for OpenProject](../../../installation-and-operations/misc/custom-openid-connect-providers/#keycloak)
 
 Once the above setup is completed, In the root `docker-compose.override.yml` file, uncomment all the environment in `backend` service for keycloak and set the values according to configuration done in keycloak for OpenProject Integration.
 

diff --git a/.../development-environment-ubuntu/README.md → ...t/development-environment/linux/README.md b/.../development-environment-ubuntu/README.md → ...t/development-environment/linux/README.md
@@ -1,6 +1,7 @@
 ---
 sidebar_navigation:
   title: Development setup on Debian / Ubuntu
+  short_title: Setup on Debian / Ubuntu
 description: OpenProject development setup on Debian / Ubuntu
 keywords: development setup debian ubuntu linux
 ---
@@ -18,8 +19,6 @@ shall NOT be present before.
 
 **Please note**: This guide is NOT suitable for a production setup, but only for developing with it!
 
-Remark: *At the time of writing* in this page refers to 12/10/2021
-
 If you find any bugs or you have any recommendations for improving this tutorial, please, feel free to send a pull
 request or comment in the [OpenProject forums](https://community.openproject.org/projects/openproject/boards).
 
@@ -350,24 +349,3 @@ in a production setting.**
 ```shell
 RAILS_ENV=development bin/rails runner "Delayed::Job.delete_all"
 ```
-
-### Start Coding
-
-Please have a look at [our development guidelines](../code-review-guidelines/) for tips and guides on how to start
-coding. We have advice on how to get your changes back into the OpenProject core as smooth as possible.
-Also, take a look at the `doc` directory in our sources, especially
-the [how to run tests](https://github.com/opf/openproject/tree/dev/docs/development/running-tests) documentation (we
-like to have automated tests for every new developed feature).
-
-### Troubleshooting
-
-The OpenProject logfile can be found in `log/development.log`.
-
-If an error occurs, it should be logged there (as well as in the output to STDOUT/STDERR of the rails server process).
-
-### Questions, Comments, and Feedback
-
-If you have any further questions, comments, feedback, or an idea to enhance this guide, please tell us at the
-appropriate community.openproject.org [forum](https://community.openproject.org/projects/openproject/boards/9).
-[Follow OpenProject on twitter](https://twitter.com/openproject), and
-follow [the news](https://www.openproject.org/blog) to stay up to date.
diff --git a/...ent/development-environment-osx/README.md → ...t/development-environment/macos/README.md b/...ent/development-environment-osx/README.md → ...t/development-environment/macos/README.md
@@ -1,6 +1,7 @@
 ---
 sidebar_navigation:
   title: Development setup on MacOS
+  short_title: Setup on MacOS
 description: OpenProject development setup on Mac OS
 keywords: development setup macos
 ---
@@ -207,8 +208,6 @@ Now, run the following tasks to migrate and seed the dev database, and prepare t
 RAILS_ENV=development bin/rails db:seed
 ```
 
-1
-
 ### Run OpenProject through overmind
 
 You can run all required workers of OpenProject through `overmind`, which combines them in a single tab. Optionally, you
@@ -334,24 +333,3 @@ in a production setting.**
 ```shell
 RAILS_ENV=development bin/rails runner "Delayed::Job.delete_all"
 ```
-
-### Start Coding
-
-Please have a look at [our development guidelines](../code-review-guidelines) for tips and guides on how to start
-coding. We have advice on how to get your changes back into the OpenProject core as smooth as possible.
-Also, take a look at the `doc` directory in our sources, especially
-the [how to run tests](https://github.com/opf/openproject/blob/dev/docs/development/running-tests) documentation (we
-like to have automated tests for every new developed feature).
-
-### Troubleshooting
-
-The OpenProject logfile can be found in `log/development.log`.
-
-If an error occurs, it should be logged there (as well as in the output to STDOUT/STDERR of the rails server process).
-
-### Questions, Comments, and Feedback
-
-If you have any further questions, comments, feedback, or an idea to enhance this guide, please tell us at the
-appropriate community.openproject.org [forum](https://community.openproject.org/projects/openproject/boards/9).
-[Follow OpenProject on twitter](https://twitter.com/openproject), and
-follow [the news](https://www.openproject.org/blog) to stay up to date.
diff --git a/docs/development/environments/README.md b/docs/development/environments/README.md
diff --git a/docs/development/localhost-ssl/README.md b/docs/development/localhost-ssl/README.md
@@ -93,7 +93,7 @@ application server. You can do that with `/usr/sbin/setsebool -P httpd_can_netwo
 ## Step 4: Configure OpenProject for HTTPS usage
 
 We assume you have already configured your OpenProject local development environment
-as [described in this guide](../development-environment-ubuntu). You will need to add your custom host name
+as [described in this guide](../development-environment). You will need to add your custom host name
 to the environment. You can use this variable to do so.
 
 ```yaml
@@ -133,10 +133,3 @@ setup a reverse proxy in docker, like [traefik](https://traefik.io/). Then follo
 
 > **Reminder**:
   This setup is still experimental and under further development. Use it only, when you know what you are doing.
-
-## Questions, Comments, and Feedback
-
-If you have any further questions, comments, feedback, or an idea to enhance this guide, please tell us at the
-appropriate community.openproject.org [forum](https://community.openproject.org/projects/openproject/boards/9).
-[Follow OpenProject on twitter](https://twitter.com/openproject), and
-follow [the news](https://www.openproject.org/blog) to stay up to date.
diff --git a/docs/development/product-development-handbook/README.md b/docs/development/product-development-handbook/README.md
@@ -343,7 +343,7 @@ The entire team documents possible improvements for the next release.
 
 ### 4.1 Version/Release
 
-A version is the name given to a collection of features and/or bugfixes. A release is the publicly available version of the OpenProject software. More information is provided on the [release page](../releases/).
+A version is the name given to a collection of features and/or bugfixes. A release is the publicly available version of the OpenProject software. More information is provided on the [Application architecture page](../application-architecture/#patch-and-change-management).
 
 ### 4.2 RICE Score
 

diff --git a/docs/development/releases/README.md b/docs/development/releases/README.md
diff --git a/docs/development/running-tests/README.md b/docs/development/running-tests/README.md
@@ -119,7 +119,7 @@ Smoke tests are automated and manual tests to ensure the main application featur
 **Best practices**
 
 - Automate smoke testing on top of manual testing when possible
-- Run after deployments to the appropriate [environments](../environments), e.g., the edge environment for features of the next release and staging environment for bug fixes to a stable release
+- Run after deployments to the appropriate [environments](../application-architecture/#environments), e.g., the edge environment for features of the next release and staging environment for bug fixes to a stable release
 - Keep smoke tests updated so that they can evolve together with the application
 
 **References**
@@ -251,7 +251,7 @@ Upgrade tests are manually performed for major code changes and data migrations
 
 #### Usability testing
 
-When new features or changes to the application are available on our [Edge or Community environments](../environments), product team members, customers, and community users can provide usability feedback on how the change is perceived.
+When new features or changes to the application are available on our [Edge or Community environments](../application-architecture/#environments), product team members, customers, and community users can provide usability feedback on how the change is perceived.
 
 **Key objectives and effects**
 
@@ -725,7 +725,7 @@ good as a test server.
 ### Running tests locally in Docker
 
 Most of the above applies to running tests locally, with some docker specific setup changes that are discussed [in the
-docker development documentation](../development-environment-docker).
+docker development documentation](../development-environment/docker).
 
 ### Generators
 

diff --git a/docs/installation-and-operations/installation/manual/README.md b/docs/installation-and-operations/installation/manual/README.md
@@ -456,8 +456,3 @@ If you need to restart the server (for example after a configuration change), do
 
   With each new OpenProject core version, the plug-ins might need to be updated. Please make sure that the plug-in versions of all you plug-ins works with the OpenProject version you use.
   Many plug-ins follow the OpenProject version with their version number (So, if you have installed OpenProject version 4.1.0, the plug-in should also have the version 4.1.0).
-
-## Questions, comments, and feedback
-
-If you have any further questions, comments, feedback, or an idea to enhance this guide, please tell us at the appropriate community [forum](https://community.openproject.org/projects/openproject/boards/9).
-[Follow OpenProject on twitter](https://twitter.com/openproject), and follow the news on [openproject.org](https://www.openproject.org) to stay up to date.