[openstreetmap/openstreetmap-website] Restructure core deveoper docs (Issue #6093)

[Emin Kocan]

kcne created an issue (openstreetmap/openstreetmap-website#6093)

### Problem

The current developer documentation, specifically `INSTALL.md`, `CONTRIBUTING.md`, and `CONFIGURE.md`, is comprehensive but can be difficult for new contributors to navigate. The information is often presented in a dense format, and the structure can make it challenging to follow a clear path from setup to contribution. This increases the onboarding friction for new developers.

*   **`INSTALL.md`**: We can improve the structure by placing the OS-specific instructions into collapsible sections to make the document easier to navigate.
*   **`CONTRIBUTING.md`**: Lacks a high-level summary of the contribution workflow and could be better organized thematically.
*   **`CONFIGURE.md`**: Is structured as a list of tasks without a clear hierarchy, making it difficult for users to find the specific configuration instructions they need.


### Description


We could refactor these key documentation files to improve their structure, clarity, and overall user experience. The goal is to make the project more welcoming and accessible to contributors.

The proposed changes are:

**1. Refactor `INSTALL.md`**
*   **Prioritize Installation Methods:** Clearly present the recommended installation paths (e.g., Docker) first.
*   **Improve Structure for Manual Installation:**
    *   Create a clear, numbered, step-by-step process (e.g., 1. Install Dependencies, 2. Clone Repo, 3. Setup Application, 4. Validate).
    *   Use collapsible `<details>` sections for platform-specific commands to reduce clutter and improve readability.
*   **Add a "What's Next?" Section:** Guide users to `CONFIGURE.md` and `CONTRIBUTING.md` after a successful installation.

**2. Refactor `CONTRIBUTING.md`**
*   **Add a Table of Contents:** For easy navigation.
*   **Create a "How to Contribute" Overview:** Provide a high-level summary of the contribution process, from finding an issue to submitting a pull request.
*   **Group Related Topics:**
    *   Combine "Coding style," "Testing," and "Static Analysis" under a "Code Quality Guidelines" heading.
    *   Group commit message and pull request guidelines under a "Submitting Changes" heading.

**3. Refactor `CONFIGURE.md`**
*   **Organize by Task:** Restructure the document around key post-installation tasks like "Populating the Database," "User Management," and "Setting up OAuth."
*   **Use Clear, Action-Oriented Headings.**
*   **Improve Instructions:** Convert paragraphs into numbered lists for clarity, especially for multi-step processes.
*   **Separate Development vs. Production:** Create a clearer distinction between configuration for a local development setup and notes for a production deployment.

These changes will make the documentation more scannable and accessible, helping developers find the information they need more efficiently and lowering the barrier to entry for new contributors.


### Screenshots

_No response_

-- 
Reply to this email directly or view it on GitHub:
https://github.com/openstreetmap/openstreetmap-website/issues/6093
You are receiving this because you are subscribed to this thread.

Message ID: <openstreetmap/openstreetmap-website/issues/6093 at github.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstreetmap.org/pipermail/rails-dev/attachments/20250611/bb4483ac/attachment.htm>