<div style="display: flex; flex-wrap: wrap; white-space: pre-wrap; align-items: center; "><img height="20" width="20" style="border-radius:50%; margin-right: 4px;" decoding="async" src="https://avatars.githubusercontent.com/u/76796906?s=20&v=4" /><strong>kcne</strong> created an issue <a href="https://github.com/openstreetmap/openstreetmap-website/issues/6093">(openstreetmap/openstreetmap-website#6093)</a></div>
<h3 dir="auto">Problem</h3>
<p dir="auto">The current developer documentation, specifically <code class="notranslate">INSTALL.md</code>, <code class="notranslate">CONTRIBUTING.md</code>, and <code class="notranslate">CONFIGURE.md</code>, 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.</p>
<ul dir="auto">
<li><strong><code class="notranslate">INSTALL.md</code></strong>: We can improve the structure by placing the OS-specific instructions into collapsible sections to make the document easier to navigate.</li>
<li><strong><code class="notranslate">CONTRIBUTING.md</code></strong>: Lacks a high-level summary of the contribution workflow and could be better organized thematically.</li>
<li><strong><code class="notranslate">CONFIGURE.md</code></strong>: Is structured as a list of tasks without a clear hierarchy, making it difficult for users to find the specific configuration instructions they need.</li>
</ul>
<h3 dir="auto">Description</h3>
<p dir="auto">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.</p>
<p dir="auto">The proposed changes are:</p>
<p dir="auto"><strong>1. Refactor <code class="notranslate">INSTALL.md</code></strong></p>
<ul dir="auto">
<li><strong>Prioritize Installation Methods:</strong> Clearly present the recommended installation paths (e.g., Docker) first.</li>
<li><strong>Improve Structure for Manual Installation:</strong>
<ul dir="auto">
<li>Create a clear, numbered, step-by-step process (e.g., 1. Install Dependencies, 2. Clone Repo, 3. Setup Application, 4. Validate).</li>
<li>Use collapsible <code class="notranslate"><details></code> sections for platform-specific commands to reduce clutter and improve readability.</li>
</ul>
</li>
<li><strong>Add a "What's Next?" Section:</strong> Guide users to <code class="notranslate">CONFIGURE.md</code> and <code class="notranslate">CONTRIBUTING.md</code> after a successful installation.</li>
</ul>
<p dir="auto"><strong>2. Refactor <code class="notranslate">CONTRIBUTING.md</code></strong></p>
<ul dir="auto">
<li><strong>Add a Table of Contents:</strong> For easy navigation.</li>
<li><strong>Create a "How to Contribute" Overview:</strong> Provide a high-level summary of the contribution process, from finding an issue to submitting a pull request.</li>
<li><strong>Group Related Topics:</strong>
<ul dir="auto">
<li>Combine "Coding style," "Testing," and "Static Analysis" under a "Code Quality Guidelines" heading.</li>
<li>Group commit message and pull request guidelines under a "Submitting Changes" heading.</li>
</ul>
</li>
</ul>
<p dir="auto"><strong>3. Refactor <code class="notranslate">CONFIGURE.md</code></strong></p>
<ul dir="auto">
<li><strong>Organize by Task:</strong> Restructure the document around key post-installation tasks like "Populating the Database," "User Management," and "Setting up OAuth."</li>
<li><strong>Use Clear, Action-Oriented Headings.</strong></li>
<li><strong>Improve Instructions:</strong> Convert paragraphs into numbered lists for clarity, especially for multi-step processes.</li>
<li><strong>Separate Development vs. Production:</strong> Create a clearer distinction between configuration for a local development setup and notes for a production deployment.</li>
</ul>
<p dir="auto">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.</p>
<h3 dir="auto">Screenshots</h3>
<p dir="auto"><em>No response</em></p>

<p style="font-size:small;-webkit-text-size-adjust:none;color:#666;">—<br />Reply to this email directly, <a href="https://github.com/openstreetmap/openstreetmap-website/issues/6093">view it on GitHub</a>, or <a href="https://github.com/notifications/unsubscribe-auth/AAK2OLKRGSU3TLV2TRDYMT33DAEKZAVCNFSM6AAAAAB7CGXVWGVHI2DSMVQWIX3LMV43ASLTON2WKOZTGEZTMNBQHEYTGOI">unsubscribe</a>.<br />You are receiving this because you are subscribed to this thread.<img src="https://github.com/notifications/beacon/AAK2OLPGUDRBWZJDYXV6CNL3DAEKZA5CNFSM6AAAAAB7CGXVWGWGG33NNVSW45C7OR4XAZNFJFZXG5LFVJRW63LNMVXHIX3JMTHLV4OOGM.gif" height="1" width="1" alt="" /><span style="color: transparent; font-size: 0; display: none; visibility: hidden; overflow: hidden; opacity: 0; width: 0; height: 0; max-width: 0; max-height: 0; mso-hide: all">Message ID: <span><openstreetmap/openstreetmap-website/issues/6093</span><span>@</span><span>github</span><span>.</span><span>com></span></span></p>

<script type="application/ld+json">[
{
"@context": "http://schema.org",
"@type": "EmailMessage",
"potentialAction": {
"@type": "ViewAction",
"target": "https://github.com/openstreetmap/openstreetmap-website/issues/6093",
"url": "https://github.com/openstreetmap/openstreetmap-website/issues/6093",
"name": "View Issue"
},
"description": "View this Issue on GitHub",
"publisher": {
"@type": "Organization",
"name": "GitHub",
"url": "https://github.com"
}
}
]</script>