Hujjatlashtirish bo'yicha eng yaxshi amaliyotlar

Sifatli hujjatlashtirish foydalanuvchilarning mahsulotingiz bilan muvaffaqiyat qozonishi yoki qiynalishi o'rtasidagi farqdir. Ushbu qo'llanma haqiqatan ham yordam beradigan hujjatlarni yozish bo'yicha isbotlangan amaliyotlarni qamrab oladi.

Yozish printsiplari

1. Auditoriyangizni biling

Yozishdan oldin o'ylab ko'ring:

• Kim o'qiyapti? (yangi boshlovchilar, ekspertlar yoki ikkalasi ham?)

• Ular nimalarni amalga oshirishi kerak?

• Ular buni qachon o'qiydilar? (o'rganish paytidami yoki muammolarni bartaraf etishdami?)

Tilingizni va ma'lumot chuqurligini shunga qarab sozlang.

2. Maqsaddan boshlang

Har bir sahifa quyidagi savolga javob berishi kerak: "Buni o'qigandan keyin foydalanuvchi nima qila oladi?"

      

        markdown
        
          
          
        
      
    ❌ "Ushbu sahifa autentifikatsiya tizimini tushuntiradi."

✅ "Buni o'qib chiqqandan so'ng, siz ilovangizda foydalanuvchilarni
   autentifikatsiya qilishni va sessiyalarni boshqarishni o'rganasiz."

3. Qisqa bo'ling

O'quvchilar vaqtini hurmat qiling:

• Keraksiz so'zlarni olib tashlang

• Qisqa paragraflardan foydalaning

• Uzun bo'limlarni bo'laklarga bo'ling

• Asosiy maqsadga tezroq o'ting

4. Faqat aytib bermasdan, ko'rsating

Tushuntirishlarni misollar bilan bog'lang:

      

        markdown
        
          
          
        
      
    ❌ "API so'rovlarini amalga oshirish uchun `fetch` funksiyasidan foydalaning."

✅ "API so'rovlarini amalga oshirish uchun `fetch` funksiyasidan foydalaning:

   ```javascript
   const response = await fetch('/api/users');
   const users = await response.json();
   ```"

Tuzilma va tashkil qilish

Axborot arxitekturasi

Hujjatlarni mantiqiy tartibda tashkil qiling:

      

        plaintext
        
          
          
        
      
    1. Ishni boshlash (o'rganish)
   ├── Kirish
   ├── O'rnatish
   └── Tezkor ishga tushirish

2. Asosiy tushunchalar (tushunish)
   ├── Arxitektura
   ├── Asosiy atamalar
   └── Bu qanday ishlaydi

3. Qo'llanmalar (amalga oshirish)
   ├── Umumiy vazifalar
   ├── Murakkab foydalanish
   └── Eng yaxshi amaliyotlar

4. Ma'lumotnoma (qidirish)
   ├── API ma'lumotnomasi
   ├── Konfiguratsiya
   └── Muammolarni bartaraf etish

Sahifa tuzilmasi

Har bir sahifa quyidagilarga ega bo'lishi kerak:

1. Aniq sarlavha - Bu sahifa nima haqida?

2. Kirish - Nima uchun buni o'qishim kerak?

3. Zaruriy shartlar - Birinchi navbatda nima kerak?

4. Content - Asosiy ma'lumotlar

5. Keyingi qadamlar - Bu yerdan qayerga borishim kerak?

Sarlavhalardan unumli foydalaning

      

        markdown
        
          
          
        
      
    # Sahifa sarlavhasi (har bir sahifada bitta)

## Asosiy bo'limlar (asosiy mavzular)

### Kichik bo'limlar (qo'llab-quvvatlovchi tafsilotlar)

#### Qo'shimcha bo'limlar (kamdan-kam hollarda kerak bo'ladi)

Yozish uslubi

Faol ovoz (Active Voice)

      

        markdown
        
          
          
        
      
    ❌ "Konfiguratsiya fayli ildiz katalogida yaratilishi kerak."

✅ "Konfiguratsiya faylini ildiz katalogida yarating."

Hozirgi zamon

      

        markdown
        
          
          
        
      
    ❌ "Funksiya promise qaytaradi deb o'ylaymiz."

✅ "Funksiya promise qaytaradi."

Ikkinchi shaxs

      

        markdown
        
          
          
        
      
    ❌ "Foydalanuvchilar sozlamalarni o'zgartirishi mumkin..."

✅ "Siz sozlamalarni o'zgartirishingiz mumkin..."

Izchil terminologiya

Uslubiy qo'llanma yarating va unga amal qiling:

Kod misollari

Ularni ishga tushirish mumkin bo'lsin

      

        javascript
        
          
          
        
      
    // ❌ To'liq bo'lmagan misol
fetch('/api/users')

// ✅ To'liq, ishga tushirish mumkin bo'lgan misol
async function getUsers() {
  const response = await fetch('/api/users', {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error(`HTTP xatosi! holat: ${response.status}`);
  }

  return response.json();
}

Kutilayotgan natijani ko'rsating

      

        javascript
        
          
          
        
      
    const user = await getUser(123);
console.log(user);

// Natija:
// {
//   id: 123,
//   name: "Alisher",
//   email: "alisher@example.com"
// }

Xatolarni qayta ishlashni kiriting

Muammolar yuzaga kelganda nima qilish kerakligini ko'rsating:

      

        javascript
        
          
          
        
      
    try {
  const data = await fetchData();
} catch (error) {
  if (error.status === 401) {
    // Ruxsat berilmaganlikni qayta ishlash
  } else if (error.status === 404) {
    // Topilmaganlikni qayta ishlash
  } else {
    // Boshqa xatolarni qayta ishlash
  }
}

Vizual elementlar

Jadvallardan qachon foydalanish kerak

Jadvallar quyidagilar uchun yaxshi ishlaydi:

• Variantlarni solishtirish

• Parametrlar hujjatlari

• Xususiyatlar matritsalari

      

        markdown
        
          
          
        
      
    | Parametr | Turi | Majburiy | Tavsif |
|-----------|------|----------|-------------|
| `name` | string | Ha | Foydalanuvchining ko'rinadigan nomi |
| `email` | string | Ha | Haqiqiy elektron pochta manzili |
| `role` | string | Yo'q | Odatiy qiymat: "user" |

Ro'yxatlardan qachon foydalanish kerak

Ro'yxatlar quyidagilar uchun yaxshi ishlaydi:

• Jarayondagi qadamlar

• Xususiyatlar yoki afzalliklar

• Zaruriy shartlar

Eslatmalar va ogohlantirishlar

Muhim ma'lumotlarni ajratib ko'rsating:

Eslatma: Bu xususiyat 2.0 yoki undan yuqori versiyani talab qiladi.

Ogohlantirish: Bu amalni bekor qilib bo'lmaydi.

Maslahat: Ish oqimingizni tezlashtirish uchun klaviatura qisqartmalaridan foydalaning.

Texnik xizmat ko'rsatish (Maintenance)

Hujjatlarni yangilab turing

• Har bir reliz bilan hujjatlarni qayta ko'rib chiqing

• "Oxirgi yangilangan" vaqt belgilarini qo'shing

• Eskirgan kontentni tezda olib tashlang

Hujjatlaringizni versiyalang

• Hujjatlar versiyalarini mahsulot versiyalariga moslashtiring

• Versiyaga xos xususiyatlarni aniq belgilang

• Qo'llab-quvvatlanadigan versiyalar uchun hujjatlarni saqlang

Fikr-mulohazalarni to'plang

• "Bu foydali bo'ldimi?" degan so'rovnomalar qo'shing

• Hujjatlardagi kamchiliklarni aniqlash uchun qo'llab-quvvatlash chiptalarini (tickets) kuzatib boring

• Mashhur qidiruv so'rovlarini kuzatib boring

Yo'l qo'yiladigan keng tarqalgan xatolar

1. Bilimni mavjud deb hisoblash

      

        markdown
        
          
          
        
      
    ❌ "OAuth callback URL-ni sozlang."

✅ "OAuth callback URL-ni sozlang. Bu foydalanuvchilar
   autentifikatsiyadan o'tgandan keyin qayta yo'naltiriladigan URL.
   Mahalliy ishlanma uchun foydalaning: http://localhost:3000/callback"

2. Matn devori

Uzun kontentni quyidagilar bilan bo'ling:

• Sarlavhalar

• Ro'yxatlar (bullet points)

• Kod misollari

• Rasmlar yoki diagrammalar

3. Eskirgan skrinshotlar

• Iloji bo'lsa, matnli tavsiflardan foydalaning

• UI-dagi har bir o'zgarish bilan skrinshotlarni yangilang

• Skrinshotlarni avtomatlashtirilgan vositalardan foydalanishni o'ylab ko'ring

4. Zaruriy shartlarning yo'qligi

Har doim foydalanuvchilarga nima kerakligini ko'rsating:

• Kerakli dasturiy ta'minot/versiyalar

• Hisobni sozlash bosqichlari

• Oldindan kerak bo'lgan bilimlar

5. Buzilgan havolalar

• Ichki havolalarni muntazam ravishda tekshiring

• Iloji bo'lsa, nisbiy (relative) URL manzillardan foydalaning

• CI-da havolalarni tekshirishni sozlang

Har bir sahifa uchun nazorat ro'yxati (Checklist)

Chop etishdan oldin tekshiring:

• Sarlavha kontentni aniq tasvirlaydi

• Kirish qismi maqsadni tushuntiradi

• Zaruriy shartlar ko'rsatilgan

• Kod misollari to'liq va tekshirilgan

• Barcha havolalar ishlaydi

• Imlo va grammatika to'g'ri

• Sahifa yorug' va qorong'u rejimda ishlaydi

• Keyingi qadamlar o'quvchilarni yo'naltiradi