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
