Writing for the Web: Principles, Strategies & Best Practices

TAKEAWAYS:

• Web writing prioritizes scannability (short paragraphs, bullet points, bold keywords) and action-oriented language over formal prose.
• SEO fundamentals (meta tags, headers, internal linking) make technical content discoverable without sacrificing clarity.
• Interactive elements (FAQs, tooltips, embedded videos) reduce cognitive load for users troubleshooting IT systems.
• Mobile-first design requires concise sentences (<20 words), clear CTAs, and responsive layouts for global audiences.
• Collaborative tools (Google Docs, Confluence) streamline reviews but demand structured feedback to avoid version conflicts.
• Ethical web writing avoids dark patterns (misleading CTAs) and ensures accessibility (alt text, screen-reader compatibility).

---

Core Concepts of Web Writing

Technical writing for the web differs from print documentation in three key ways:

1. User-Centricity: Web content must solve problems immediately—users expect answers in <10 seconds.
2. Multimodal Delivery: Combines text with visuals (screenshots, GIFs), videos, and interactive widgets.
3. Dynamic Updates: Content must be modular (e.g., expandable sections) to accommodate frequent IT changes.

Key Principles

---

Step-by-Step Web Writing Process

Use this 5-phase framework for IT documentation (e.g., a Daraz seller’s FAQ page or an Ncell troubleshooting guide):

1. Audience Analysis

   • Who? Tech-savvy users (e.g., Pathao drivers) vs. novices (e.g., NTC broadband subscribers).
   • Goal? Identify pain points (e.g., "Why is my eSewa payment failing?").
   • Tool: Create user personas (e.g., "Rajesh, 28, uses WhatsApp Business but struggles with API errors").

2. Content Planning

   • Structure: Hierarchical (main topic → subtopics → details).
   • SEO Keywords: Use tools like Ubersuggest to find terms like "Khalti transaction timeout fix".
   • Example Outline for a Bank Loan Guide:

     H1: "How to Apply for a Loan on Siddhartha Bank’s Mobile App"
     H2: "Eligibility Criteria"
     H2: "Step-by-Step Application Process"
       H3: "Upload Documents (KYC, Proof of Income)"
       H3: "Submit via Mobile App"
     H2: "FAQs (e.g., ‘What if my CIBIL score is low?’)"
     

3. Writing for Readability

   • Sentence Length: Average 12–15 words (e.g., *"To reset your Ncell SIM PIN, dial 123# and follow the prompts").
   • Active Voice: "Click ‘Submit’" vs. "The form can be submitted by clicking."
   • Visual Cues:
     • Bold for commands: Ctrl + Alt + Del to restart.
     • Italics for file names: setup.exe.
     • Code blocks for error messages:

       Error: "404 Not Found"
       Solution: Verify the URL or contact Daraz Support.
       

4. Interactive & Multimedia Elements

   • FAQ Accordion (collapsible sections) for NEPSE investor queries.
   • Embedded Videos: Showing how to configure a router (e.g., NTC’s YouTube tutorials).
   • Tool Tips: Hover text for icons (e.g., "⚙️ Settings" → "Adjust notification preferences").

5. SEO Optimization

   • Meta Description: <160 characters (e.g., "Fix WhatsApp login issues on Android/iOS in 3 steps. Troubleshooting guide for Nepal users.").
   • Internal Linking: Link to related guides (e.g., "Still facing issues? See our VPN setup guide").
   • Alt Text for Images:

     ![Ncell app screenshot]("Ncell app login screen with error code 500")
     

---

Real-World Applications in Nepal

1. eSewa: Transaction Failure Guides

• Idea Used: Modular troubleshooting with dropdown menus.
• How?
  • Users select: "Payment not processed" → "Bank declined" → "Check your account balance".
  • SEO Keyword: "eSewa payment failed 2024" ranks #1 for this query.
  • Visual: Screenshot of the error page with annotated steps.

2. Daraz Seller Center: Order Fulfillment Docs

• Idea Used: Action-oriented bullet points + interactive checklist.
• How?
  • Instead of: "You must pack the order carefully."
  • Daraz uses:

    ✅ **Packing Checklist**
    - Use original packaging (if available)
    - Include invoice (auto-generated)
    - Seal with Daraz-branded tape
    - [Scan & upload proof](#)
    

  • Result: 30% faster seller onboarding (per Daraz’s 2023 report).

3. NTC Broadband: Router Setup Video + Text Guide

• Idea Used: Multimodal delivery (video + transcript).
• How?
  • Video: 2-minute tutorial showing WPS button press.
  • Text Alternative:

    Step 1: Locate the WPS button on your router (see image below). Step 2: Press and hold for 5 seconds while your device searches for networks. ![Router WPS button]("NTC Mi-Fi WPS button location")

---

Worked Example: Writing a WhatsApp Business API Guide

Scenario: A Kathmandu-based SME wants to automate customer queries via WhatsApp. You’re writing their API integration guide.

Step 1: Audience Analysis

• Primary Audience: Non-technical business owners (e.g., a momos shop using WhatsApp for orders).
• Secondary Audience: IT support staff (for debugging).

Step 2: Content Structure

# WhatsApp Business API Setup for Nepalese SMEs
**Last Updated**: June 2024
**Estimated Time**: 15 minutes

## Prerequisites
- A [Meta Business Account](https://business.facebook.com/) (free)
- A **WhatsApp Business App** (Android/iOS)
- **API Access**: Apply via [Meta’s WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api)

## Step-by-Step Integration
### 1. Connect Your Phone Number
1. Log in to [Meta Developer Dashboard](https://developers.facebook.com/).
2. Click **"Create App"** → Select **"WhatsApp"**.
3. Enter your **verified Nepalese number** (e.g., +977 98XXXXXXXX).

### 2. Configure Webhooks (for Automated Replies)
```python
# Example: Python code to send automated order confirmations
import requests

def send_confirmation(order_id):
    url = "https://graph.facebook.com/v18.0/{PHONE_ID}/messages"
    payload = {
        "messaging_product": "whatsapp",
        "to": "97798XXXXXXXX",
        "type": "text",
        "text": {"body": f"Order #{order_id} confirmed! 🎉"}
    }
    headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
    requests.post(url, json=payload, headers=headers)

Note: Replace YOUR_ACCESS_TOKEN with your Meta API token.

3. Test the API

• Send a test message to your number via the dashboard.
• Expected Output:

  [Your Business Name]: Hello! How can we help? (Options: Order Status, Return Policy)
  

Step 3: Readability Enhancements

• Bold Commands: Click "Create App".
• Warnings:

  ⚠️ Important: Ensure your number is verified in Meta Business Suite. Unverified numbers cannot send messages.

• FAQ Section:

  **Q: My API calls are failing. What should I do?**
  A: Check:
  1. Your **access token** is active (expires in 60 days).
  2. Your phone number is **sandbox-approved** (for testing).
  3. Your server’s IP is **whitelisted** in Meta’s dashboard.
  

Step 4: SEO & Accessibility

• Meta Tags:

  <meta name="description" content="Step-by-step guide to set up WhatsApp Business API for Nepalese SMEs. Includes Python code examples and troubleshooting tips.">
  

• Alt Text for Screenshots:

  ![Meta Developer Dashboard]("Meta Developer Dashboard showing WhatsApp API setup screen with phone number verification step")
  

---

Common Pitfalls & How to Avoid Them

---

Tools for Collaborative Web Writing

---

Exam Tip: How to Score Full Marks

1. Structure Your Answer Like a Web Page

   • Use subheadings (H2/H3) to mirror exam question parts.
   • Example for "Explain the copyediting phase":

     Copyediting for Web Content

     1. Technical Accuracy Check

     • Verify API endpoints (e.g., https://api.esewa.com/v2/payment).
     • Test links using Dead Link Checker.

     2. Style Consistency

     • Enforce title case for headers (e.g., "How to Reset Password").
     • Use active voice (e.g., "Submit the form" vs. "The form should be submitted").

     3. SEO Review

     • Optimize meta descriptions (<160 chars).
     • Include long-tail keywords (e.g., "Khalti payment failed Kathmandu").

2. Use Real Examples

   • Compare before/after snippets:
     • ❌ "The user must input their credentials." (passive, vague)
     • ✅ "Enter your eSewa username and 6-digit PIN below." (active, specific)

3. Highlight Collaborative Challenges

   • Mention version control (e.g., "Two team members edited the same FAQ section in Google Docs, causing conflicts").
   • Propose solutions:
     • Use track changes in Word.
     • Assign section ownership (e.g., "Rajesh handles API docs; Sita handles UI guides").

4. Ethical Dilemmas (5 Marks)

   • Scenario: Your company asks you to downplay a product’s limitations in the web guide.
   • Your Response:

     *"I would document the limitation transparently (e.g., ‘Ncell’s hotspot works best in urban areas; rural users may experience lag’). If management insists on omitting it, I would escalate to the compliance officer, citing Nepal’s Consumer Protection Act (2075)."*

5. Audience Analysis (4 Marks)

   • Question: "How would you write a guide for NTC broadband setup vs. a guide for IT professionals?"
   • Answer:

     Feature	NTC Broadband Guide (Novices)	IT Professional Guide (Experts)
     Tone	Friendly, step-by-step	Concise, command-line focused
     Visuals	Screenshots + arrows	ASCII diagrams + curl commands
     Error Handling	"Contact NTC at 1660"	"Debug with tcpdump; check /var/log/syslog"
     Assumptions	User has no prior tech knowledge	User knows Linux basics

---

Pro Tip: For 5-mark questions on collaborative writing, describe a specific tool (e.g., Confluence) and its Nepalese use case (e.g., "Ncell’s IT team uses Confluence spaces to track changes in their router firmware guides").

---

Visuals for This Unit (real objects/apps):