Yaxshi README yozish
Loyiha turi va o‘quvchiga mos README shablonlari va yozish bo‘yicha maslahatlar.
Tushuntirish tanlangan tilda; prompt matni inglizcha qoladi.
Nima uchun kerak
Loyihaga README yozayotgan yoki eskirganini yangilayotgan dasturchi uchun: kim o‘qishiga qarab to‘g‘ri shablon va savollar ketma-ketligi.
Qanday ishlatiladi
Avval vazifani ayting: yaratish, qo‘shish, yangilash yoki tekshirish. Keyin loyiha turini (ochiq manba, shaxsiy, ichki), bir gapda u hal qiladigan muammoni va ishga tushirishning eng qisqa yo‘lini yozing.
Qisqa namuna
Vazifa: yaratish. Tur: shaxsiy loyiha. Muammo: Telegram kanal uchun postlarni jadval bo‘yicha yuboruvchi skript. Ishga tushirish: pip install va bitta buyruq.
Kutiladigan natija
Auditoriyaga mos tuzilma: nima qiladi, o‘rnatish, foydalanish, kerakli bo‘limlar; oxirida “yana nimani qo‘shay?” degan savol.
Ehtiyot choralari va maslahatlar
- README ichiga parol, token va shaxsiy yo‘llarni qo‘ymang.
- Foydalanish misollarini o‘zingiz ishga tushirib tekshiring.
- Loyiha o‘zgarsa, README ni ham yangilab, sanani yozib qo‘ying.
# Crafting Effective READMEs
## Overview
READMEs answer questions your audience will have. Different audiences need different information - a contributor to an OSS project needs different context than future-you opening a config folder.
**Always ask:** Who will read this, and what do they need to know?
## Process
### Step 1: Identify the Task
**Ask:** "What README task are you working on?"
| Task | When |
|------|------|
| **Creating** | New project, no README yet |
| **Adding** | Need to document something new |
| **Updating** | Capabilities changed, content is stale |
| **Reviewing** | Checking if README is still accurate |
### Step 2: Task-Specific Questions
**Creating initial README:**
1. What type of project? (see Project Types below)
2. What problem does this solve in one sentence?
3. What's the quickest path to "it works"?
4. Anything notable to highlight?
**Adding a section:**
1. What needs documenting?
2. Where should it go in the existing structure?
3. Who needs this info most?
**Updating existing content:**
1. What changed?
2. Read current README, identify stale sections
3. Propose specific edits
**Reviewing/refreshing:**
1. Read current README
2. Check against actual project state (package.json, main files, etc.)
3. Flag outdated sections
4. Update "Last reviewed" date if present
### Step 3: Always Ask
After drafting, ask: **"Anything else to highlight or include that I might have missed?"**
## Project Types
| Type | Audience | Key Sections | Template |
|------|----------|--------------|----------|
| **Open Source** | Contributors, users worldwide | Install, Usage, Contributing, License | `templates/oss.md` |
| **Personal** | Future you, portfolio viewers | What it does, Tech stack, Learnings | `templates/personal.md` |
| **Internal** | Teammates, new hires | Setup, Architecture, Runbooks | `templates/internal.md` |
| **Config** | Future you (confused) | What's here, Why, How to extend, Gotchas | `templates/xdg-config.md` |
**Ask the user** if unclear. Don't assume OSS defaults for everything.
## Essential Sections (All Types)
Every README needs at minimum:
1. **Name** - Self-explanatory title
2. **Description** - What + why in 1-2 sentences
3. **Usage** - How to use it (examples help)
## References
- `section-checklist.md` - Which sections to include by project type
- `style-guide.md` - Common README mistakes and prose guidance
- `using-references.md` - Guide to deeper reference materialsPrompt matni asl inglizcha holida, tarjima qilinmagan: sun’iy intellekt vositasiga shundayligicha joylashtiring. [Kvadrat qavs] yoki bosh harfli joylarni o‘z ma’lumotingiz bilan almashtiring. Javobni har doim tekshiring.
Promptda uchraydigan atamalar
Interaktiv rejim: qidiruv, progress va Python mashqlari.