Docs/clarify feature setup

[atishaykeploy]

UX Documentation Review: Quickstart - NextJS Improvements

Contributor: @atishaykeploy
Date: October 9, 2025

---

1. Issue: Oversized Typography (Primary Readability Pain Point)

❌ Before (Visual Representation)

• Problem Description: The primary page titles (NextJs Sample Application) and section headings (Introduction, Platform-Specific Requirements for Keploy) are excessively large, creating visual clutter and an aggressive feel. This increases cognitive load and degrades the user experience, especially on larger screens.
• Targeted Elements: All <h1>, <h2>, and potentially <h3> heading tags.
• Uneven Padding: The padding above the page title (NextJs Sample Application) seems uneven, which undermines the first look of the page.

---

✅ Recommendation: Optimize Heading Font Sizes

• Changes Proposed:
  1. Although there's a difference in font and theme for Keploy, the crisp headings and coherent padding is recommended, like that in the NextJS Documentation.
  2. The font size is visibly low, which gives a good view on the default zoom of the browser - be it on a samll or big screen.

---

2. Issue: Combined Commands Hiding Execution Flow

❌ Before (Problem Screenshot)

• Description of Problem: The initial setup command combines git clone and cd using &&. This hides the execution flow and prevents users from verifying the success of the clone step before changing the directory. It also complicates the process if the user wishes to debug or use an existing directory.
• Relevant Section: The "Get Started!" section of the NextJS + SQL guide.

---

✅ Recommendation: Separate Commands for Clarity

📋 Proposed Solution

The instruction should be broken into two distinct, sequential, and highly copyable commands:

# Clone the repository
git clone [https://github.com/keploy/samples-typescript](https://github.com/keploy/samples-typescript)

# Change into the application directory
cd samples-typescript/nextjs-postgres

3. Issue: Minor Typographical Error

❌ Before (Problem Screenshot)

• Description of Problem: The sentence below the "Get Started!" heading contains a typo: "Now that we have bun installed, we will se tup our application."

---

✅ Recommendation: Correct the Typos for Polish

• Implementation Change: Correct the sentence in the source Markdown file to use the word "up".
  • Proposed Text: "Now that we have bun installed, we will set up our application."
• UX Outcome: Ensures the documentation is professional, error-free, and trustworthy.

4. Issue: Uneven Heading Hierarchy (Inconsistent Styling)

❌ Before (Visual Representation)

• Description of Problem: The headings in the "Generate testcases" section are inconsistent. "Generate testcases" uses one style, while "1. Create Post request" uses a different, mixed style (numbered list + bold) for a subordinate item.
• UX Impact: This inconsistent styling makes it difficult for users to visually scan and understand the relationship between the different steps and sections. It breaks the expected documentation hierarchy.

---

✅ Recommendation: Standardize Hierarchy and Formatting

• Implementation Change:
  1. Ensure "Generate testcases" uses a consistent heading level (e.g., ## Generate testcases).
  2. Ensure subsequent steps are consistently styled ordered list items with appropriate heading style (1. Create Post request).
• UX Outcome: Creates a clean, predictable, and scannable visual structure, clearly defining parent-child relationships in the documentation.

5. Issue: Docker Command Requires Root Privileges (sudo)

❌ Before (Problem Screenshot)

• Description of Problem: The command docker-compose up often fails for users without specific Docker group permissions, resulting in a "Permission Denied" error. This forces users to stop, troubleshoot their system setup, or search for a fix.
• Relevant Section: "start the database instance" section under "Get Started!"
• Root Cause: On many systems, the docker command requires sudo privileges if the user isn't correctly added to the docker user group.

---

✅ Recommendation: Provide Robust, Alternative Command

• Implementation Change: Update the code block to include sudo as the default or clearly offer it as an alternative in the instructions text.

  • Proposed Command:

    # Start the database instance (use 'sudo' if you encounter permission errors)
    sudo docker-compose up -d

• Additional UX Fix: The command should typically include the -d (detached) flag, which is standard practice for running services like databases in the background.

• UX Outcome: Eliminates a common setup roadblock by guiding the user immediately to the working command, reducing frustration and successful completion of the "Get Started" flow.