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/6...@github.com>
_______________________________________________
rails-dev mailing list
rails-dev@openstreetmap.org
https://lists.openstreetmap.org/listinfo/rails-dev

Reply via email to