Skip to content

STYLE.md

Latest commit

 

History

History
133 lines (77 loc) · 3.18 KB

STYLE.md

File metadata and controls

133 lines (77 loc) · 3.18 KB

Style Guidance

Keploy documentation generally follows the Google Developer Documentation Style Guide.

When the Google guide does not address a specific topic, we defer to the Microsoft Writing Style Guide.

🛠️ Keploy-Specific Style Guidelines

The following are Keploy-specific rules that override or expand on the Google and Microsoft guides.

📌 Capitalization of Core Terms

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.

✅ Correct:

“Next, Normalise the Test case on the Test run details page.”

❌ Incorrect:

“Next, normalise the test case on the test run details.”

🔤 Sentence Case in Headings

Use sentence case for all titles and headings. This means only the first word and proper nouns are capitalized.

✅ Correct:

How to get started with Keploy

❌ Incorrect:

How To Get Started With Keploy

🧾 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.