0Pricing
AI Prompt Engineering · Ders

Teknik Belgeleme İstemleri

Doğru teknik anlatımla README dosyaları, API belgeleri ve nasıl yapılır kılavuzları oluşturun.

Teknik Belgeleme İstemleri, CoddyKit'te ücretsiz bir AI Prompt Engineering dersidir. Bu, 4 dersinin 3. dersidir. Aşağıdan dersin tamamını ücretsiz okuyabilir, sonra tarayıcıda yerleşik kod editörü ve 7/24 yapay zeka koçu ile uygulamalı olarak pratik yapabilirsin. Bu, AI Prompt Engineering öğrenme yolunun bir parçasıdır ve ilerlemeniz web ve CoddyKit uygulaması arasında senkronize olur. AI Prompt Engineering kursu toplamda 4 dersten oluşur.

Teknik Belgeler Bir Yazın Türüdür

Teknik belgeler belirli kuralları olan farklı bir yazın türüdür: üsluptan önce kesinlik, anlatıdan önce yapı, özlülükten önce eksiksizlik. Blog gönderileri veya e-postalar için işe yarayan istemler, teknik belgeler için uygun olmayan bir dil kullanımı üretir.

Etkili teknik belge istemleri, türü açıkça tanımlar — belge türünü, okuyucunun sahip olduğu varsayılan bilgi düzeyini, o belge türü için standart yapıyı ve anlatım kuralını (genellikle nasıl yapılır kılavuzlarında ikinci şahıs, başvuru belgelerinde üçüncü şahıs) belirtir.

README Dosyası İstemleri

README bir projenin giriş noktasıdır. Standart yapısı iyi belirlenmiştir. Etkili bir README istemi her bölümü belirtir:

  • Proje adı ve tek satırlık açıklama
  • Ne yaptığı: amacı açıklayan 2-3 cümle
  • Ön koşullar: yüklenmiş olması gerekenler
  • Kurulum: komutları içeren numaralı adımlar
  • Hızlı başlangıç: asgari çalışan örnek
  • Yapılandırma: ortam değişkenleri ve seçenekler
  • Katkıda bulunma: birleştirme isteklerinin nasıl gönderileceği
  • Lisans

Tüm bölüm adlarını istemde sağlamak eksiksiz bir README oluşturur. Açıkça talimat verilmezse eksik bölümler atlanır.

Kodda README İstemi

Proje üst verilerini kabul eden yapılandırılmış bir README oluşturucu:

import openai

client = openai.OpenAI(api_key='sk-...')

def generate_readme(project_name, description, language, dependencies,
                    install_steps, quick_start_example, config_vars, license_type):

    prompt = f'''Write a README.md for the following project.

Project name: {project_name}
Description: {description}
Language/stack: {language}
Dependencies: {dependencies}
Installation steps: {install_steps}
Quick start example: {quick_start_example}
Key configuration variables: {config_vars}
License: {license_type}

Structure the README with these sections in order:
1. Project title and badge line (GitHub stars, license)
2. One-sentence description
3. Features (3-5 bullet points)
4. Prerequisites
5. Installation (numbered steps with code blocks)
6. Quick Start (minimal working example in a code block)
7. Configuration (table: Variable | Description | Default)
8. Contributing (2-3 sentences)
9. License

Voice: second person imperative for steps ("Run...", "Install...").
Code blocks: use correct language identifiers.
Do not add placeholder content — only include sections where I provided information.'''

    response = client.chat.completions.create(
        model='gpt-4o-mini',
        messages=[{'role': 'user', 'content': prompt}]
    )
    return response.choices[0].message.content

API Belgesi İstemleri

API belgeleri katı bir yapıya sahiptir. Her uç nokta kaydı şunları içermelidir: HTTP yöntemi, yol, açıklama, parametreler, istek gövdesi, yanıt biçimi, hata kodları ve bir örnek. İstemler bunların tümünü belirtmelidir:

"Bir REST uç noktası için API belgeleri yazın. Şunları ekleyin: yöntem (POST), yol (/api/v1/users), açıklama, parametre tablosu (ad, tür, zorunlu, açıklama), istek gövdesi JSON örneği, başarı yanıtı (200) JSON örneği, JSON örnekleriyle hata yanıtları (400, 401, 422). Anlatım: üçüncü şahıs, şimdiki zaman. Parametreler için Markdown tabloları kullanın."

Her yapısal unsur açıkça adlandırılmalıdır — model belge standardınızı tahmin etmez.

Nasıl Yapılır Kılavuzu İstemleri

Nasıl yapılır kılavuzları prosedüreldir: okuyucuyu numaralandırılmış adımlar aracılığıyla A durumundan (sorun) B durumuna (çözüm) götürür. Nasıl yapılır kılavuzları için istem öğeleri:

  • Ön koşullar: başlamadan önce doğru olması gerekenler
  • Sonuç: okuyucunun neyi başarmış olacağı
  • Adımlar: numaralandırılmış olmalı; her adım tek bir eylem içermeli, bir adımda birden çok eylem bulunmamalıdır
  • Kod örnekleri: uygun olduğunda her adım için bir örnek ve kullanılan dil belirtilmelidir
  • Doğrulama: okuyucunun her adımın başarıyla tamamlandığını nasıl anlayacağı
  • Sorun giderme: en zor iki veya üç adım için yaygın başarısızlık durumları

Belgelendirme İstemlerinde Teknik Doğruluk

Teknik belgelendirmede doğruluk gereksinimi, çoğu içerik türündekinden daha yüksektir. Belgelendirme istemlerinde doğruluğu artırmak için iki teknik:

Gerçek kodu sağlayın: gerçek işlev imzalarını, yapılandırma seçeneklerini veya API belirtimini yapıştırın. Model, ayrıntıları uydurmak yerine gerçekten var olanı belgeler.

Bir doğrulama adımı isteyin: "Her adımı yazdıktan sonra kullanıcının ortamı veya sistemin davranışı hakkında yaptığınız varsayımları belirtin. Yayımlamadan önce doğrulamam gereken her şeyi işaretleyin."

Yapay zekâ tarafından oluşturulan belgelendirmeyi teknik inceleme olmadan asla kullanmayın — model, var olmayan veya hatalı şeyleri kendinden emin bir şekilde belgeleyebilir.

Belgelerde Kod Örneği Kalitesi

Kod örnekleri, teknik belgelendirmenin en önemli öğesidir. İsteminizde bunları açıkça belirtin:

  • "Her ana kavram için çalışan bir kod örneği ekleyin. Örnekler kendi içinde eksiksiz olmalı; okuyucu bunları kopyalayıp yapıştırarak çalıştırabilmelidir."
  • "Hem doğru kullanımı hem de yaygın bir hatayı gösterin ve hatanın neden başarısız olduğunu açıklayan bir yorum ekleyin."
  • "Kod örneklerinde 'foo', 'bar', 'deneme' yerine gerçekçi değişken adları ve veriler kullanılmalıdır."
  • "Dil: Python 3.11. Tür ipuçlarını kullanın. Ağ çağrısı için hata işleme ekleyin."

Açık kod örneği talimatları olmadan model, gerçekte çalışmayan eksik sözde kod parçacıkları üretebilir.

Belgelendirme Anlatımı ve Üslubu

Teknik belgelendirmenin, diğer yazı türlerinden farklı belirli bir anlatımı vardır:

  • Prosedürlerde ikinci kişi emir kipi: "Ayarlar'a tıklayın. API sekmesini seçin. Anahtarınızı girin."
  • Başvuru belgelerinde üçüncü kişi: "authenticate() yöntemi, 24 saat geçerli bir Bearer belirteci döndürür."
  • Geniş zaman: "İşlev döndürür..."; "İşlev döndürecek..." değil
  • Belirsizlik ifadeleri kullanmama: "Bu komutu çalıştırın"; "Bu komutu çalıştırmayı düşünebilirsiniz" değil
  • Tutarlı terminoloji: aynı kavram için metnin tamamında aynı terimi kullanın; eş anlamlılar kullanmayın

Değişiklik Günlüğü ve Sürüm Notları İstemleri

Değişiklik günlükleri ve sürüm notları, istemlerin yansıtması gereken geleneksel bir biçime sahiptir:

"2.3.0 sürümü için sürüm notları yazın. Biçim: Sürüm başlığı, sürüm tarihi ve ardından üç bölüm: 'Eklendi' (yeni özellikler), 'Değiştirildi' (mevcut özelliklerdeki değişiklikler), 'Düzeltildi' (hata düzeltmeleri). Her öğe: tek satır, etken çatı ve bir fiille başlamalıdır. Hedef kitle: bu kitaplığı entegre eden geliştiriciler. Üslup: kesin ve tarafsız; pazarlama dili kullanmayın. Değişiklikler şunlardır: [gerçek değişiklikleri listeleyin]."

Gerçek değişiklikleri girdi verisi olarak sağlamak doğruluğu güvence altına alır. Bunlar sağlanmadığında model, kulağa inandırıcı gelen ancak uydurma sürüm notları oluşturur.

Belgelendirme Eksiksizlik Denetimi

Teknik belgelendirmeyi oluşturduktan sonra bir eksiksizlik denetimi istemi çalıştırın:

import openai

client = openai.OpenAI(api_key='sk-...')

def check_documentation_completeness(doc_text, doc_type='how-to guide'):
    checklist = {
        'how-to guide': [
            'Prerequisites stated?',
            'Expected outcome stated?',
            'Each step is a single action?',
            'Code examples included where relevant?',
            'Validation step for each major action?',
            'Common errors addressed?'
        ],
        'readme': [
            'One-line description present?',
            'Installation steps numbered with commands?',
            'Quick start example included?',
            'Configuration variables documented?',
            'License specified?'
        ]
    }

    items = checklist.get(doc_type, [])
    check_prompt = f'Review this {doc_type} and answer each question (Yes/No + brief note):\n'
    for item in items:
        check_prompt += f'- {item}\n'
    check_prompt += f'\nDocument:\n{doc_text[:2000]}'

    response = client.chat.completions.create(
        model='gpt-4o-mini',
        messages=[{'role': 'user', 'content': check_prompt}]
    )
    return response.choices[0].message.content

Karma Kitleler İçin Jargonu Çevirme

Teknik belgelendirmenin çoğu zaman hem teknik hem de teknik olmayan okuyuculara hitap etmesi gerekir. Uygulanabilir bir istem kalıbı:

"Bu belgelendirmeyi iki katman halinde yazın. İlk katman: 3 cümlelik teknik olmayan bir özet (ne yaptığı, neden önemli olduğu, ne zaman kullanılacağı). İkinci katman: eksiksiz teknik belirtim. Katmanlar arasında belirgin bir görsel ayraç kullanın. Böylece teknik olmayan yöneticiler özeti okuyup durabilir; teknik okuyucular ise özeti atlayarak belirtimi okuyabilir."

İki katmanlı belgelendirme, her iki kitleye de yetersiz biçimde hizmet eden tek bir sürüm yazmaya çalışmaktan daha kullanışlıdır.

Bilgi Sınaması: Teknik Belgelendirme İstemleri

50 uç nokta için API belgelendirmesi oluşturmak üzere istemler yazıyorsunuz. En önemli kalite gereksinimi, belgelendirmenin modelin API'nin ne yaptığını hayal ederek yazdıklarını değil, API'nin gerçekte ne yaptığını doğru biçimde yansıtmasıdır. Doğruluğu en iyi hangi yaklaşım güvence altına alır?

Özet: Teknik Belgelendirme İstemleri

Teknik belgelendirme; prosedürlerde kesinlik, yapı ve ikinci kişi emir kipi gerektiren ayrı bir türdür. Etkili istemler belge türünü, gerekli bölümleri adlarıyla, kod örneği gereksinimlerini (kendi içinde eksiksiz olma, gerçekçi değişken adları, dil sürümü) ve belgelendirme anlatımı kuralını belirtir.

En kritik doğruluk tekniği şudur: gerçek kodu, API belirtimini veya yapılandırma verilerini her zaman girdi olarak sağlayın; teknik ayrıntıları asla modelin uydurmasını istemeyin. Yapay zekâ tarafından oluşturulan belgelendirmeyi yayımlamadan önce mutlaka insan tarafından teknik inceleme yapılmasını sağlayın.

Son derste istem yazma tekniklerini yaratıcı ve öykü anlatımı içeriklerine uygulayacaksınız.

Sıkça Sorulan Sorular

“Teknik Belgeleme İstemleri” dersi ücretsiz mi?

Evet — “Teknik Belgeleme İstemleri” dersin tüm metni burada web'de ücretsiz olarak okunabilir. Etkileşimli olarak pratik yapmak (yerleşik kod editörü ve 7/24 yapay zeka koçu) ve AI Prompt Engineering kursunun geri kalanını açmak için CoddyKit PRO'ya yükselt. AI Prompt Engineering kursu toplamda 4 dersten oluşur.

“Teknik Belgeleme İstemleri” dersinde ne öğreneceğim?

Doğru teknik anlatımla README dosyaları, API belgeleri ve nasıl yapılır kılavuzları oluşturun. AI Prompt Engineering ile uygulamalı kodu tarayıcıda doğrudan çalıştırarak pratik yaparsın ve 7/24 yapay zeka koçu dersi çalışırken sorularını yanıtlar.

AI Prompt Engineering öğrenmeye başlamak için deneyim gerekli mi?

Önceden deneyim gerekmez. CoddyKit'te AI Prompt Engineering, başlangıçtan ileri seviyeye kadar yapılandırıldığı için buradan başlayabilir veya başından başlayıp kendi hızında ilerleme yapabilirsin. Bu, 4 dersinin 3. dersidir.

“Teknik Belgeleme İstemleri” dersi ne kadar sürer?

Çoğu CoddyKit dersi yaklaşık 5–10 dakika sürer. Her biri kısa ve etkileşimli olduğu için sabit ilerleme yaparsın ve web ile uygulama arasında tam olarak bıraktığın yerden devam edebilirsin.

Bu AI Prompt Engineering dersinde kod yazıp çalıştırabilir miyim?

Evet. Her AI Prompt Engineering dersi yerleşik bir kod editörü içerir, bu sayede tarayıcıda gerçek kod yazıp çalıştırabilir ve anlık yapay zeka geri bildirimi alırsın — yerel kurulum gerekli değildir.

Bu kursun tüm dersleri

  1. E-posta ve Profesyonel Yazım İstemleri
  2. Sosyal Medya İçeriği İstemleri
  3. Teknik Belgeleme İstemleri
  4. Yaratıcı Yazarlık ve Hikâye Anlatımı İstemleri
← AI Prompt Engineering Sayfasına Dön