हम कौन-सी समस्या हल कर रहे हैं?

टीमें शीर्षक, alt text और contrast को याद रखती हैं, लेकिन यह भूल जाती हैं कि examples भी content हैं। पृष्ठ ठीक दिख सकता है, पर सबसे महत्वपूर्ण हिस्सा — code example, JSON response या field table — पढ़ने में कठिन, रंग पर निर्भर, या screen reader के लिए असुविधाजनक हो सकता है।

एक अच्छी guide केवल सलाह नहीं देती; वह उसी लेख के भीतर सही pattern दिखाती है: संदर्भ, अपेक्षित परिणाम, स्पष्ट संरचना और ऐसा पाठ जो रंग हटाने पर भी अर्थ बनाए रखे।

सुलभ उदाहरणों के सिद्धांत

  1. Code block से पहले लक्ष्य बताइए।
  2. रंग को अर्थ का एकमात्र माध्यम न बनाइए।
  3. सफलता, चेतावनी और त्रुटि को अलग दिखाइए।
  4. तालिका तभी प्रयोग करें जब सचमुच rows और columns का संबंध हो।
  5. एक cell में एक तथ्य और एक example में एक मुख्य उद्देश्य रखें।

उदाहरण 1. पहले उद्देश्य समझाइए, फिर अनुरोध दिखाइए

रिपोर्ट 42 प्राप्त करें। <token> को वैध access token से बदलें। सफल अनुरोध पर सर्वर HTTP 200 और status = ready वाला JSON लौटाता है।

GET /v1/reports/42 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
{
  "id": 42,
  "status": "ready",
  "download_url": "/v1/reports/42/file"
}
{
  "error": "not_found",
  "message": "रिपोर्ट 42 मौजूद नहीं है या अब उपलब्ध नहीं है।"
}

उदाहरण 2. तालिका के शीर्षक ही अर्थ दें

फ़ील्ड प्रकार अनिवार्य अर्थ टिप्पणी
id integer हाँ रिपोर्ट पहचानकर्ता हर सफल प्रतिक्रिया में
status string हाँ प्रोसेसिंग स्थिति सामान्य मान: queued, running, ready, failed
download_url string नहीं फ़ाइल लिंक केवल status = ready पर
error string नहीं त्रुटि कोड केवल असफल प्रतिक्रिया में
जाँच प्रश्न अच्छा संकेत
लक्ष्य क्या उदाहरण का उद्देश्य स्पष्ट है? पाठक पहले से परिणाम समझ लेता है
संरचना क्या सफलता और त्रुटि अलग हैं? अलग blocks या labels हैं
तालिका क्या headers अर्थ स्पष्ट करते हैं? cell header के साथ समझ में आता है
भाषा क्या व्याख्या साफ़ और संक्षिप्त है? पाठ उदाहरण को समझने में मदद करता है

उदाहरण 3. जब structure महत्त्वपूर्ण हो, markup दिखाइए

<table>
  <caption>रिपोर्ट प्रतिक्रिया के फ़ील्ड</caption>
  <thead>
    <tr>
      <th scope="col">फ़ील्ड</th>
      <th scope="col">प्रकार</th>
      <th scope="col">अनिवार्य</th>
      <th scope="col">अर्थ</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row"><code>status</code></th>
      <td>string</td>
      <td>हाँ</td>
      <td>वर्तमान प्रोसेसिंग स्थिति</td>
    </tr>
  </tbody>
</table>

किन बातों से बचें

  • बिना संदर्भ के code block;
  • सफलता या त्रुटि केवल रंग से दिखाना;
  • प्रक्रियाओं या लंबे अनुच्छेदों के लिए तालिकाएँ;
  • एक cell में कई असंबंधित तथ्य;
  • copyable text की जगह code के screenshots।

लेखक के लिए व्यावहारिक pattern

  1. लक्ष्य
  2. पूर्व शर्त
  3. उदाहरण
  4. अपेक्षित परिणाम
  5. सामान्य त्रुटि
  6. आवश्यकता होने पर संदर्भ तालिका

छोटा editorial checklist

  • Code block से पहले उद्देश्य बताइए।
  • सफलता और त्रुटि अलग रखिए।
  • कोड को बिना रंग के भी समझने योग्य बनाइए।
  • तालिका केवल वास्तविक tabular relation के लिए उपयोग कीजिए।
  • screenshots की जगह copyable text दीजिए।

संबंधित सामग्री