docs: improve README formatting and clarity (#544)

* docs:Improved README formatting and tips

* Full rewrite and expansion of style guide

---------

Co-authored-by: Neha Gupta <[email protected]>

Author: KaramjeetKaur1428

README.md

@@ -10,7 +10,8 @@ Repository for the Keploy documentation website.
 </p>
 </div>
 
-**Note** :- Issue Creation is disabled on this Repository, please visit [here](https://github.com/keploy/keploy/issues/new/choose) to submit Issue.
+> ⚠️ **Note:** Issue creation is disabled in this repository.  
+> To submit a new issue, please visit the [Keploy community forum](https://github.com/keploy/dashboard/issues) or the main repo’s issue tracker.
 
 <p align="center">
 <a href="https://github.com/keploy/docs" alt="GitHub contributors">
@@ -75,6 +76,9 @@ npm start
 
 The command starts a local development server and opens a browser window.
 
+> 💡 **Tip:** After running `npm install`, use `npm start` to preview changes live at `http://localhost:3000/`.
+
+
 ## Running Vale Locally for Documentation Linting
 
 To help maintain consistency in our documentation, we use Vale, a syntax-aware linter that checks for spelling, grammar, and style issues.

STYLE.md

@@ -1,50 +1,121 @@
-# Style guidance
+# Style Guidance
 
-In general, Keploy content follows the [Google developer documentation style guide](https://developers.google.com/style).
-When the Google guide is silent about an issue, we follow the [Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/).
+Keploy documentation generally follows the [Google Developer Documentation Style Guide](https://developers.google.com/style).  
 
-## Keploy-specific style guidance
+When the Google guide does not address a specific topic, we defer to the [Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/).
 
-We have a few Keploy-specific style guidelines that override the Google and Microsoft guides.
+---
 
-### Capitalization of core terms
+## 🛠️ Keploy-Specific Style Guidelines
 
-Many of Keploy's core terms can be used in a generic way.
-To differentiate one of Keploy's core terms from a generic instance of a term, always treat the Keploy term as a proper noun in documentation.
-Generic versions of the same term should not be capitalized and should be used sparingly to avoid confusion.
+The following are Keploy-specific rules that override or expand on the Google and Microsoft guides.
 
-- Correct: "Next, Normalise the Test case on the Test run details."
-- Incorrect: "Next, normalise the test case on the test run details"
+---
 
-### En dashes in ranges
+### 📌 Capitalization of Core Terms
 
-Using an en dash (`–` or the character `–`) in a range of numbers is acceptable.
-Even better is to use words such as _from_, _to_, and _through_.
+Some of Keploy’s core terms may also exist as generic terms in software or technical contexts.  
+To reduce confusion, **always capitalize Keploy-specific terms** when referring to features or platform components. Generic usage should be lowercase and used sparingly.
 
-Be consistent.
-If you use an en dash in one range, use en dashes in all ranges.
-Do not mix words and en dashes (or hyphens, for that matter).
+✅ **Correct:**  
+> “Next, Normalise the Test case on the Test run details page.”
 
-- Correct: "5 to 10 GB"
-- Correct: "5–10 GB"
-- Correct: "5-10 GB"
-- Incorrect: "from 5-10 GB"
+❌ **Incorrect:**  
+> “Next, normalise the test case on the test run details.”
 
-## Headings
+---
 
-Although the following guidance is provided by both the Google and Microsoft guides, we want to emphasize how we style headings.
+### 🔤 Sentence Case in Headings
 
-### Infinitive verb forms in headings
+Use **sentence case** for all titles and headings. This means only the **first word** and **proper nouns** are capitalized.
 
-Titles and headings should use infinitive verb forms whenever possible. People tend to search by using infinitive verb forms, so using them helps SEO.
+✅ Correct:
+> How to get started with Keploy
 
-- Correct: "Install Keploy"
-- Incorrect: "Installing Keploy"
+❌ Incorrect:
+> How To Get Started With Keploy
 
-### Sentence casing in headings
+---
 
-Use sentence casing for titles and headings.
-Sentence casing means that only the first letter of the first word and proper nouns are capitalized.
+### 🧾 Infinitive Verb Forms in Headings
+
+Use **infinitive verb forms** (e.g., "to install", "to create", "to configure") in titles and headings.  
+This improves searchability and aligns with common SEO practices.
+
+✅ Correct:
+> Install Keploy  
+> Create test cases
+
+❌ Incorrect:
+> Installing Keploy  
+> Creating test cases
+
+---
+
+### 🧮 En Dashes in Ranges
+
+Use **en dashes (–)** to indicate numeric ranges. Do **not** mix styles or use hyphens inconsistently.  
+You may also use words like *from*, *to*, or *through* — but be consistent throughout the doc.
+
+✅ Correct:
+- 5–10 GB
+- 5 to 10 GB
+
+❌ Incorrect:
+- from 5-10 GB
+- 5–10 GB and 10 to 20 MB (mixed style)
+
+---
+
+### 🧠 Use Active Voice
+
+Use **active voice** instead of passive voice to improve clarity and readability.
+
+✅ Correct:
+> Keploy records the API calls and generates test cases.
+
+❌ Incorrect:
+> The API calls are recorded and test cases are generated by Keploy.
+
+---
+
+### 🌍 Write for Global Readability
+
+Use clear, simple, and **inclusive language**:
+- Avoid jargon or unexplained acronyms.
+- Provide context for technical terms.
+- Prefer short, direct sentences.
+
+✅ Better:
+> After installing Go, use the following command to run Keploy.
+
+❌ Confusing:
+> Assuming GOPATH is set and your binaries are globally linked, execute Keploy.
+
+---
+
+### 🔧 Code Formatting
+
+- Wrap inline code using backticks: \`like this\`
+- Use triple backticks for multi-line code blocks:
+    \`\`\`bash  
+    npm install  
+    npm run serve  
+    \`\`\`
+- Add comments in code examples where needed for clarity.
+
+---
+
+## ✅ Summary Checklist for Writers
+
+- [ ] Are headings in sentence case and infinitive form?
+- [ ] Are core terms capitalized correctly?
+- [ ] Did I use active voice wherever possible?
+- [ ] Are numeric ranges formatted consistently?
+- [ ] Is my language clear and globally understandable?
+- [ ] Are code examples formatted properly?
+
+---
+
+> ✨ _Consistency leads to clarity. Let’s keep Keploy documentation clean, helpful, and easy to follow._
 
-- Correct: "How to get started with Keploy"
-- Incorrect: "How To Get Started With Keploy"