Create developement.md

contributing/developement.md

@@ -0,0 +1,46 @@
+1. Explanation for npm ci and npm install
+You mention that npm ci performs a clean install, but it could be clarified why this is important (e.g., consistency with the package-lock.json file).
+Add a note about why npm install is not preferred here (e.g., it modifies the package-lock.json).
+Suggested Update:
+
+npm ci is used for a clean and reproducible installation of dependencies, ensuring the package-lock.json file remains consistent. Unlike npm install, it skips dependency updates.
+
+2. ENABLED_LANGUAGES Clarification
+It's great that you provide an example for enabling specific languages, but you could mention the default behavior (e.g., only English is enabled unless otherwise specified).
+Suggested Update:
+
+By default, only English (en) is enabled for the local server. To enable other languages...
+
+3. Mention of ./debugging-the-docs-application.md
+The reference to this file is helpful, but ensure it's actually included in the repository and up-to-date.
+If the file is not directly accessible or relevant, consider rephrasing or removing the reference.
+Suggested Update:
+
+For advanced debugging tips and setup with VSCode, see "Debugging the Docs Application." Ensure this file is present in your working branch.
+
+4. Codespaces Section
+The Codespaces section is brief and useful but could benefit from a note about its benefits (e.g., no local setup required) or prerequisites (e.g., having access to GitHub Codespaces).
+Suggested Update:
+
+With GitHub Codespaces, you can bypass local setup entirely, saving time and ensuring a consistent development environment. Note that Codespaces may require specific access permissions for your GitHub account.
+
+5. History of the Site's Development
+The history of the site moving from Rails to Jekyll to Nanoc to Node.js is interesting but could confuse newcomers. You might want to mention that this is for context and that no Ruby knowledge is necessary to contribute now.
+Suggested Update:
+
+While the site has a history of evolving through various technologies (Rails, Jekyll, Nanoc), it is now fully powered by Node.js. No prior Ruby knowledge is needed to contribute.
+
+6. Internal Links
+Some links to files like liquid-helpers.md and lib/languages.js are relative paths. Ensure these paths are valid and work when the document is viewed from the intended context (e.g., a GitHub repository or local Markdown viewer).
+Suggested Update: Verify that all relative links resolve correctly. For example:
+
+[liquid-helpers.md](liquid-helpers.md) should be adjusted if its context changes.
+7. Bookmarklets Section
+The mention of bookmarklets is intriguing, but its purpose could be more explicit. Why are these helpful? Who benefits most from using them?
+Suggested Update:
+
+The src/bookmarklets directory contains browser shortcuts that streamline the review process for GitHub documentation. These are particularly useful for power users and documentation reviewers.
+
+8. Typographical Suggestions
+Use consistent capitalization for headings (e.g., “Getting Started” vs. “Using GitHub Codespaces”).
+Avoid overuse of emojis unless the document aims for a playful tone.