Ürün olarak belgelendirme

Spec: ISO/IEC/IEEE 26514 Spec: ISO/IEC/IEEE 26513 Spec: ISO 24495-1 Evidence: Standard-backed

Bir bakışta

Bu sayfalar bir belgelendirme kalite modeline göre oluşturulur, sade dil temeline ve katmanlı bir biçem hiyerarşisine bağlı kalınarak yazılır ve motor kodunda çalışanlarla aynı türde otomatik geçitlerle denetlenir. Bu sayfa, söz konusu disiplini ve NextPDF’in bir belgelendirme kusurunu neden mühendislik kusuru olarak kaydettiğini açıklar.

Bu sayfa; kendinden emin görünen ancak doğrulanamayan belgeler yüzünden zarar görmüş ve onlara güvenmeden önce bu belgeleri farklı kılanın ne olduğunu bilmek isteyen kıdemli bir mühendis için yazılmıştır.

Bu neden önemli

Bir belge kitaplığı güven üzerine satın alınır ve bu güvenin kazanıldığı ya da kaybedildiği yer belgelendirmedir. Fark edemeyeceğiniz biçimde yanlış olan bir sayfa, hiç sayfa olmamasından daha kötüdür. Temkinli yaklaşımınızı yersiz bir güvene dönüştürür. Sonunda hata, üzerinde sizin adınız olan commit’le üretimde ortaya çıkar.

Standart literatürü bu riskler konusunda açıktır. İyi tasarlanmış kullanıcı bilgileri, destek maliyetini düşürmekten fazlasını yapar; ürünün ve onu üretenin itibarını yükseltir. Bu, doğrulama ve geçerleme testini geliştirme sürecinin sonrasına değil, içine yerleştirerek kazanılır Spec: ISO/IEC/IEEE 26513, §Foreword . NextPDF bunu kelimesi kelimesine uygular: belgelendirme, kalite eşiği olan bir ürün yüzeyidir; kodun yanına eklenmiş bir nezaket unsuru değildir.

Kısa özeti

NextPDF, bu belgeleri §8 kullanıcı bilgisi ölçütlerinden türetilen açık bir bilgi kalitesi modeline tabi tutar: bir sayfa teknik olarak doğru olmalı, tek ve tutarlı bir sözcük dağarcığı kullanmalı, belirtilen okuyucusu tarafından anlaşılabilir olmalı, yalnızca gerekeni söyleyip gerekli hiçbir şeyi atlamamalı ve yardımcı teknoloji için erişilebilir kalmalıdır Spec: ISO/IEC/IEEE 26514, §8 .
Yapı doğaçlama değildir. Konular, bir okuyucunun bir sayfayı tanıyarak bulabilmesi için üst veriyle dondurulmuş bir hiyerarşi içinde düzenlenir (bölüm, hedef kitle, kanıt düzeyi) Spec: ISO/IEC/IEEE 26514, §9 ve en önemli ifade her sayfanın üst kısmına yakın yer alır Spec: ISO 24495-1, §5 .
Üslup, onaylanmış bir biçem hiyerarşisi tarafından yönetilir — ton için Apple, yordam için Microsoft, kod için Google ve bunların tümünde sade dil — ve her sapma, geçersiz kıldığı kaynak madde ile birlikte depo içinde kayda geçirilir.
Kalite makineyle denetlenir. Vale, üslup paketlerini zorunlu kılar; bir dizi composer docs:* geçidi bağlantı bütünlüğünü, atıf temizliğini, aynen alınmış hiçbir standart metin bulunmamasını ve gizli ayrıntıların hiçbir biçimde sızmamasını zorunlu kılar.
Belgeler kodla birlikte, yinelemeli olarak geliştirilir — her değişiklik belgelendirmesini de birlikte teslim eder, belgelendirmesini biriken işlere bırakmaz Spec: ISO/IEC/IEEE 26515, §Introduction .

NextPDF buna nasıl yaklaşır

Yazıya dökülmüş bir kalite modeli

“İyi belgeler” ifadesi, nitelikleri adlandırılana kadar yanlışlanamaz. NextPDF, §8 kullanıcı bilgisi ölçütlerini, her Insider_ sayfasının ölçüldüğü eşik olarak kendi terimleriyle yeniden ifade eder: her sayfa teknik olarak doğru olmalı, tek ve tutarlı bir sözcük dağarcığına bağlı kalmalı, belirtilen okuyucusu tarafından anlaşılabilir olmalı, gerekli hiçbir şeyi atlamadan yalnızca o okuyucunun gereksinim duyduğu bilgiyi taşımalı ve yardımcı teknoloji için erişilebilir kalmalıdır Spec: ISO/IEC/IEEE 26514, §8 . Bunlar sıfat değildir; inceleme ölçütleridir. “Gerekli ama eksiksiz” sınaması, bir sayfanın doldurma yapmak yerine sınırını açıkça çizip orada durmasının nedenidir. Sözcük dağarcığı tutarlılığı, terminolojinin yönetilmesinin nedenidir (aşağıda). Erişilebilirlik, her bileşenin klavye ve ekran okuyucu kullanımında güvenli olmasının ve hiçbir zaman yalnızca renkle işaret vermemesinin nedenidir.

Zevke göre değil, çözümlemeye göre yapı

Insider_ taksonomisi, herhangi bir sayfa yazılmadan önce dondurulur. Bu bilinçli bir tercihtir. ISO 26514, hedef kitle ve görev çözümlemesinin, bilgi tasarımından önce gelmesini gerektirir Spec: ISO/IEC/IEEE 26514, §9 . Ayrıca, kullanıcıların gereksinim duyduklarını hızla bulabilmesi için konuların, her biri hedef kitlesini ve bilgi türünü tanımlayan üst veri taşıyacak biçimde hiyerarşiler ya da gruplar hâlinde düzenlenmesini gerektirir Spec: ISO/IEC/IEEE 26514, §9 . Bu depoda söz konusu üst veri somut bir ön bilgi alanıdır — section, audience, evidence_level, tags — ve küme haritası tek ve dondurulmuş bir dosyadır. Bir okuyucu sayfayı tanıyarak seçer; hiç kimsenin bir slug’ı hatırlaması gerekmez.

Bir sayfanın iç düzeni sabittir ve her yerde aynıdır; en yararlı ifade ise okuyucunun onu ilk bulacağı yere, çoğunlukla başlangıca yerleştirilir Spec: ISO 24495-1, §5 . Her Insider_ sayfasının ayrıntıdan önce Kısa özeti bölümünü koymasının nedeni budur: bir okuyucu üç bölümden sonra okumayı bırakabilir ve yine de savunulabilir bir yanıtla ayrılabilir.

Kanıtlarıyla bir biçem hiyerarşisi

Üslup, yazarın o anki ruh hâline bırakılmaz. Depo, onaylanmış bir geçersiz kılma belgesi (docs/style/nextpdf-overrides.md) içerir; bu belge, Apple’ı (ton), Microsoft MSTP’yi (yordam ve arabirim terimleri) ve Google DDSG’yi (kod ve CLI) sade dil ve denetimli sözcük dağarcığı temellerinin üzerine katmanlar hâlinde yerleştirir ve her kip için bir çatışma çözüm tablosu içerir. En katı kural hepsinin önüne geçer: lisanslı bir standartlar kuruluşundan aynen alınmış hiçbir metin kullanılmaz. NextPDF’in bir kaynak kılavuzdan saptığı her nokta, geçersiz kıldığı kaynak madde ve gerekçesiyle birlikte kayda geçirilir. Biçem belgesi, kendi kaynaklarını bir sayfanın yaptığı gibi gösterir.

Körü körüne güvenmek zorunda olmadığınız kalite

Disiplin, iyi niyetlerle değil, araçlarla zorunlu kılınır:

Scaffold The page starts from a populated front-matter and section skeleton.
Vale packs Apple, MSTP, Google, and controlled-vocabulary rules run on the prose.
Link check docs:link-check rejects link rot against the built site.
NDA scan docs:nda-scan rejects private FQCNs and internal artefact names.
Quote fingerprint docs:jaccard-fingerprint flags verbatim standards-text reuse.
Citation audit docs:rag-citation-check / docs:rag-fallback-check guard the digests.
Review A reviewer confirms the page's declared evidence level holds.

Belgelendirme kalite geçitleri, bir sayfanın bunlardan geçtiği sırayla: doldurulmuş bir iskelet yapıyı sabitler; Vale üslup paketlerini zorunlu kılar; docs:* geçitleri bağlantı bütünlüğünü, atıf temizliğini, hiçbir aynen alınmış standart metni olmamasını ve hiçbir gizli sızıntı olmamasını zorunlu kılar; inceleme ise kanıt temelini doğrular. Bir geçidi geçemeyen sayfa bir kusurdur ve başarısız bir test gibi ele alınır.

Bunlar, bu deponun composer.json dosyasındaki gerçek girdilere karşılık gelir. docs:lint, NDA ve bağlantı geçitlerini yerel olarak çalıştırır. docs:jaccard-fingerprint, benzerlik eşiğinin üzerindeki aynen alınmış standart metin kullanımını işaretler. docs:rag-fallback-check, atıf bütünlüğü protokolünün tümüyle uygulanmış, çevrimdışı ve belirlenimci bir zorlayıcısıdır. Canlı RAG yeniden doğrulaması (docs:rag-citation-check) ve bazı tarayıcılar, daha derin çalıştırıcıları henüz geliştirilmekte olan geçitler olarak bağlanmıştır. Dürüst ifade şudur: sözleşme onaylanmıştır ve yapısal denetimler bugün zorunlu kılınmaktadır; her denetimi kapsamlı hâle getirme çabası ise sürmektedir. Insider_, hak etmediği yeşil bir gösterge panosu sunmaz — ki bu da kalite modelinin bu sayfaya uygulanan “doğru” ölçütünün ta kendisidir.

Kanıt ne diyor

Bu sayfa, belgelendirme kalitesi iddiaları için Evidence: Standard-backed niteliğindedir ve zorunlu kılma iddiaları için depo içinde temellendirilmiştir. Bu ikili temel bilinçli bir tercihtir: ilkeler standartlardan gelir; zorunlu kılma ise depo okunarak doğrulanabilir.

İddia	Temel	Dayanak
Belgelerin tanımlı bir kalite eşiği vardır	Standart	Doğru, tek sözcük dağarcıklı, okuyucu tarafından anlaşılabilir, gerekli ama eksiksiz, yardımcı teknoloji için erişilebilir Spec: ISO/IEC/IEEE 26514, §8
Terminoloji yönetilir	Standart	Bilgi kümesi boyunca tutarlı terminoloji Spec: ISO/IEC/IEEE 26514, §8
Yapı, yazmadan önce gelir	Standart	Tasarımdan önce hedef kitle ve görev çözümlemesi Spec: ISO/IEC/IEEE 26514, §9
En yararlı ifade önce gelir	Standart	En önemli mesaj başta Spec: ISO 24495-1, §5
Belgeler kodla birlikte teslim edilir	Standart	Her yinelemenin çıktıları kullanıcı bilgilerini içerir Spec: ISO/IEC/IEEE 26515, §Introduction
Kalite makineyle denetlenir	Depo içinde	`composer.jsondocs:*` geçitleri; onaylanmış `docs/style/nextpdf-overrides.md`; etkin Vale yapılandırması

Pratik örnek

Disiplin en küçük ölçekte bile kendini gösterir: bir kalite verisi metne hiçbir zaman elle yazılmaz, çünkü metindeki bir sayı sessizce eskir. Bu veri, bir değer uydurmayı reddeden ve sayfanın kanıt temeliyle desteklenen bir bileşen tarafından oluşturulur:

<?php

declare(strict_types=1);

// Illustrative: the documentation build's contract for a quality datum.
// The component throws if no real value is supplied — a metric is never
// allowed to live as a hardcoded literal that can drift out of date.
final class QualityDatum
{
    public function __construct(
        public readonly string $label,
        public readonly string $value,
    ) {
        if ($this->value === '') {
            throw new \InvalidArgumentException(
                'A quality datum must carry a verified value; '
                . 'documentation never invents a metric.',
            );
        }
    }
}

$phpstanLevel = new QualityDatum(label: 'PHPStan', value: 'Level 10');

Asıl mesele throw ifadesidir. Bilgi kalitesi modelinin “doğru” ölçütü burada öneri niteliğinde değildir; yapı bunu zorunlu kılar, böylece eskimiş bir rakam sessizce yayımlanamaz.

Yaygın yanlış kanı

Tuzak, “bir ürün olarak belgelendirme” ifadesini cilaya ilişkin bir slogan olarak okumaktır — daha güzel bir metin, daha şık sayfalar. Bu, görünüşe odaklanmanın tam tersidir. Bunun anlamı, belgelerin tanımlı bir kalite eşiği, yönetilen bir sözcük dağarcığı, dondurulmuş bir yapı ve makineyle denetlenen geçitler taşımasıdır. Bunlardan herhangi birini geçemeyen bir sayfa, düzeltilmesi gereken bir kusurdur ve başarısız bir test gibi ele alınır. Cila, disiplinin amacı değil, bir yan ürünüdür.

İkinci tuzak, sözleşme var diye her geçidin hâlihazırda kapsamlı olduğunu varsaymaktır. Değildir ve bu sayfa bunu açıkça belirtir. Yapısal denetimler bugün zorunlu kılınmaktadır; daha derin doğrulayıcılar ise geliştirilmektedir. Aksini ileri sürmek, tam da bu sayfanın açıkladığı kalite modelini ihlal ederdi.

Sınırlar ve kapsam dışı

Bu sayfa, belgelendirme disiplinini açıklar. Biçem belgesinin, taksonomi dosyasının ya da geçit uygulamalarının kendisi değildir. Hiçbir motor davranışı iddiasında bulunmaz. Yetkili kaynaklar depo içindedir (docs/style/nextpdf-overrides.md, dondurulmuş taksonomi, composer.json docs:* betikleri) ve bunlarla farklılık oluşursa buradaki herhangi bir özeti geçersiz kılar.

Zorunlu kılma yüzeyi, dürüstçe kabul etmek gerekirse kısmidir. Atıf bütünlüğü yedek denetimi etkindir. Bağlantı ve NDA geçitleri yerel olarak çalışır. Aynen alıntı ve canlı atıf doğrulayıcıları bağlanmıştır, ancak kapsamlı çalıştırıcıları henüz tamamlanmaktadır. Bu, tamamlanmış bir durum olarak değil, sürmekte olan iş olarak bildirilir. Bu sayfanın Premium katman belgelendirmesine değindiği yerlerde, açıklanan disiplin süreç düzeyinde geçerlidir; hiçbir zaman herhangi bir kamuya açık olmayan mekanizma düzeyinde geçerli değildir.

İlgili belgeler

Atıf disiplini — biçem hiyerarşisindeki en katı kural ve bu sayfanın dayandığı kanıt düzeyi sistemi.
Standartlar manzarası — bu disiplinin atıfta bulunduğu standartlar ve bir maddenin nasıl belgelenmiş davranışa dönüştüğü.
NextPDF tasarım felsefesi — bir belgelendirme kusurunu bir kod kusuru gibi ele alan mühendislik anlayışı.

Sözlük

Bilgi kalitesi modeli — NextPDF’in, her Insider_ sayfası için inceleme eşiği olarak kullanılan ISO 26514 §8 kullanıcı bilgisi ölçütlerini (doğru, tek sözcük dağarcıklı, okuyucu tarafından anlaşılabilir, gerekli ama eksiksiz, yardımcı teknoloji için erişilebilir) yeniden ifade edişi.
Sade dil — sözcükleri, yapısı ve tasarımıyla hedeflenen okuyucuların içeriği bulmasını, anlamasını ve kullanmasını sağlayan iletişim; bir içerik türü değil, tüm kiplerde uygulanan bir temel.
Biçem hiyerarşisi — her NextPDF sapmasının kaynağına karşı kayda geçirildiği, onaylanmış ve katmanlı kaynak biçem kılavuzları kümesi (Apple, Microsoft, Google ile birlikte sade dil ve denetimli sözcük dağarcığı temelleri).
Kalite geçidi — bir sayfanın geçmesi gereken otomatik bir denetim (bir Vale paketi ya da bir composer docs:* betiği); bir başarısızlık, önemsiz bir kusur değil, bir belgelendirme kusurudur.
Ön bilgi üst verisi — konu düzenleme gereksinimine uygun olarak bir sayfayı bulunabilir ve sınıflandırılabilir kılan makine tarafından okunabilir başlık (section, audience, evidence_level, tags).