Dyscyplina cytowania

Spec: ISO/IEC/IEEE 26514Spec: ISO 24495-1

W skrócie

To strona, do której odwołuje się reszta Insider_, gdy wyjaśnia, jak cytuje standard. Wyjaśnia, dlaczego ta dokumentacja parafrazuje specyfikacje, zamiast je cytować, jak twierdzenie wskazuje standard i dokładną klauzulę, na której się opiera, oraz co czyste cytowanie obiecuje, a czego nie.

Powstała z myślą o doświadczonym inżynierze, który zanim zaufa twierdzeniu, chce poznać reguły, według których je sformułowano, i ma do tego pełne prawo.

Dlaczego to ma znaczenie

Każda pozostała strona Insider_ formułuje twierdzenia i wiąże je z nazwanym standardem i klauzulą. To cytowanie ma wartość tylko wtedy, gdy stojąca za nim dyscyplina jest jawna. Jeśli „oparte na standardzie” mogłoby oznaczać cokolwiek — od „uważnie przeczytałem specyfikację” po „mniej więcej pamiętam, co tam było” — cytowanie jest tylko dekoracją.

Istnieje też trudniejsze ograniczenie. Wiele dokumentów, którym podlega NextPDF — specyfikacje ISO, ETSI i podobne — jest objętych licencją. Powielanie ich treści, niezależnie od długości fragmentu, jest niedozwolone. Dyscyplina musi zatem rozwiązać dwa problemy naraz: uczynić twierdzenie prześledzalnym do jego źródła bez powielania tego źródła. Odpowiedzią na oba problemy jest precyzyjne cytowanie i wierna parafraza, a niniejsza strona jest ich specyfikacją.

Wersja skrócona

Insider_ parafrazuje standardy i nigdy nie cytuje standardów objętych licencją. Twierdzenie wskazuje standard i dokładną klauzulę; nie powiela słów standardu.
Parafraza nie jest obejściem; to test zrozumienia. Przeformułowanie wymagania własnym językiem NextPDF zmusza autora do jego zrozumienia i utrzymuje terminologię spójną ze słownikiem Spec: ISO/IEC/IEEE 26514, §8.
Każde twierdzenie oparte na standardzie wskazuje konkretną klauzulę lub sekcję, a nie cały dokument, dzięki czemu kolejny recenzent może otworzyć tę klauzulę i potwierdzić w niej parafrazę.
Cytowanie podaje rodzaj źródła, na którym się opiera — klauzulę, kod silnika, test, pomiar — tak aby przesadne twierdzenie było widoczne na pierwszy rzut oka.
Gdy twierdzenia nie da się powiązać z klauzulą, którą autor faktycznie przeczytał, nie jest ono fabrykowane. Zostaje zachowane, oznaczone jako nierozwiązane, a strona pozostaje nieopublikowana — to udokumentowany protokół, a nie improwizacja.

Jak podchodzi do tego NextPDF

Parafraza, nie cytat

Najsurowsza reguła w hierarchii stylu NextPDF ma pierwszeństwo przed każdym nadrzędnym dokumentem z wytycznymi: żadnego dosłownego tekstu z licencjonowanej organizacji normalizacyjnej, niezależnie od tego, jak krótki jest fragment. Zamiast tego strona wskazuje standard i klauzulę oraz parafrazuje wymaganie własnym językiem.

Zwykle ujmuje się to jako ograniczenie licencyjne i tym właśnie jest. Redakcyjnie bardziej użyteczne jest jednak inne ujęcie. Dosłowny cytat dowodzi jedynie tego, że autor potrafi kopiować. Wierna parafraza pokazuje, że autor zrozumiał klauzulę na tyle dobrze, by przeformułować ją bez zmiany znaczenia. Pozwala też utrzymać zdanie w spójnym słownictwie NextPDF, zamiast zmieniać rejestr w połowie strony; takiej spójności wymaga model jakości dokumentacji Spec: ISO/IEC/IEEE 26514, §8. Prosty język ocenia się na podstawie tego, czy czytelnik potrafi znaleźć, zrozumieć i wykorzystać treść, a nie tego, czy tekst odwzorowuje źródło Spec: ISO 24495-1, §Introduction; parafraza temu służy, a cytat nie.

Twierdzenie wskazuje klauzulę, a nie tylko dokument

Mechanizmem, który czyni parafrazę sprawdzalną, jest precyzja. Każde twierdzenie oparte na standardzie wskazuje dokładną klauzulę lub sekcję, na której się opiera — na przykład ISO 32000-2 §6 — a nie tylko dokument. Recenzent nie musi ufać pamięci autora; otwiera tę klauzulę i porównuje ją z przeformułowaniem. Odniesienie do klauzuli jest łącznikiem między niecytowalnym źródłem a weryfikowalnym twierdzeniem. Wskazuje, gdzie szukać, bez przenoszenia tekstu samego źródła.

Cytowanie mówi, jakiego rodzaju jest to źródło

Cytowanie odpowiada na pytanie „skąd”. Musi też odpowiedzieć na pytanie „jakiego rodzaju”. Stwierdzenie, że twierdzenie opiera się na klauzuli standardu, to inna obietnica niż stwierdzenie, że opiera się na własnym kodzie silnika, na teście lub na pomiarze. NextPDF utrzymuje te rodzaje rozdzielone, aby czytelnik mógł je rozważyć: kod i testy stoją ponad zachowaniem w środowisku uruchomieniowym, środowisko uruchomieniowe ponad metadanymi, a metadane ponad prozą. Strona redakcyjna, taka jak ta, nie udaje, że jest oparta na kodzie.

Rodzaj źródła	Co obiecuje	Czego nie obiecuje
Oparte na kodzie	Twierdzenie jest sprawdzane względem kodu źródłowego silnika lub uruchamialnego przykładu	Że wymaga tego standard
Oparte na standardzie	Twierdzenie jest zakotwiczone w przywołanej, sparafrazowanej klauzuli	Że kod obecnie wdraża to bez wyjątku
Oparte na testach	Test w zestawie utrzymuje to zachowanie w miejscu	Wartości wydajnościowej
Oparte na benchmarku	Pomiar wykonany według podanej metody potwierdza tę wartość	Tej samej wartości na twoim sprzęcie
Oparte na artefakcie	Wytworzony artefakt (wynik kompilacji, raport) to demonstruje	Wymogu standardu
Zasada projektowa	Świadoma, uargumentowana decyzja projektowa	Pomiaru empirycznego
Redakcyjne	Uzasadnione wyjaśnienie, które porządkuje pozostały materiał	Nowej, samodzielnej gwarancji behawioralnej
Mieszane	Strona łączy różne podstawy i wskazuje, która dotyczy którego twierdzenia	Jednej, czystej podstawy

Ta strona jest redakcyjna: nie deklaruje żadnego własnego zachowania silnika. Wyjaśnia dyscyplinę, na której opierają się cytowania pozostałych stron. To dla niej uczciwa podstawa, a powiedzenie tego wprost jest zastosowaniem tej samej dyscypliny do siebie.

Gdy źródła nie da się przeczytać

Dostęp do standardu nie zawsze jest natychmiastowy — licencjonowana specyfikacja może być taką, którą autor musi dopiero zdobyć, albo klauzula może wymagać drugiej lektury, zanim jej znaczenie stanie się jasne. Integralność dyscypliny ujawnia się w tym, co dzieje się wówczas. Autor nie zgaduje. Twierdzenie, którego nie da się jeszcze powiązać z klauzulą, którą autor faktycznie przeczytał, zostaje zachowane, powiązane z materiałem w repozytorium oraz odniesieniem do standardu, które deklaruje sam kod, jawnie oznaczone jako nierozwiązane, a strona pozostaje nieopublikowana, dopóki klauzula nie zostanie poprawnie zacytowana.

Zakazane działania są wyliczone i sprawdzalne: numer klauzuli wymyślony tak, by wyglądał na precyzyjny, cytowanie ubrane tak, jakby zostało przeczytane, choć spisano je z pamięci, albo ciche usunięcie twierdzenia, by uniknąć cytowania. Poprawnie oznaczone otwarte cytowanie w wersji roboczej to dług z adnotacją, a nie wada. Offline’owa, deterministyczna kontrola wymusza dokładnie to rozróżnienie.

Praktyczny przykład

Dyscyplina ma konkretną postać: to struktura sekcji citations w nagłówku strony. Każdy wpis wiąże twierdzenie z jego klauzulą.

citations:
  - spec: "ISO 32000-2"
    clause: "§6"
    # NextPDF-worded topic — the paraphrase, never the standard's text
    topic: "A writer's created or amended PDF elements must conform and stay consistent"

Z założenia nie ma pola quote. Pole topic to własne przeformułowanie NextPDF. Pola spec i clause to sposób, w jaki recenzent wraca do dokładnego źródła, by sprawdzić to przeformułowanie. Wpis niesie wskaźnik do klauzuli, a nie słowa samej klauzuli.

Częste nieporozumienie

Pułapką jest odczytanie „parafrazuj, nie cytuj” jako asekuracji — sposobu, by brzmieć autorytatywnie bez zobowiązania. Jest odwrotnie. Cytat do niczego nie zobowiązuje; zapożycza cudze słowa. Przywołana parafraza zobowiązuje autora do przeformułowania, które recenzent może podważyć na podstawie klauzuli. Dyscyplina czyni twierdzenia bardziej rozliczalnymi, a nie mniej.

Drugą pułapką jest traktowanie „redakcyjnego” jako słabszej odmiany „opartego na standardzie”. To nie jest odmiana; to inny rodzaj. Strona redakcyjna, taka jak ta, porządkuje i wyjaśnia pozostały materiał. Jest poprawnie oznaczona. I to oznaczenie jest sednem: system działa, ponieważ strona informuje, na jakiego rodzaju źródle się opiera, zanim zdecydujesz, jaką wagę mu nadać.

Granice i ograniczenia

Ta strona określa dyscyplinę cytowania; nie jest arkuszem stylu ani kodem bramki. Miarodajne artefakty znajdują się w repozytorium (docs/style/nextpdf-overrides.md §5 oraz skrypty composer.jsondocs:*) i mają pierwszeństwo przed jakimkolwiek streszczeniem tutaj, jeśli wystąpi rozbieżność. Nie deklaruje żadnego zachowania silnika.

Dyscyplina wiąże twierdzenie, a nie wniosek czytelnika. Wiernie przywołana parafraza mówi, czego wymaga klauzula. To, czy odczyt NextPDF jest tym, którego wymaga dane zobowiązanie, pozostaje decyzją czytelnika, dlatego strony behawioralne zawierają także cytowania oparte na kodzie lub testach, a nie tylko na standardzie. Egzekwowanie jest częściowe, co przyznajemy uczciwie: offline’owa kontrola działa, a weryfikatory dosłownego cytatu i aktywnego cytowania są podłączone, lecz ich kompletne mechanizmy uruchamiania wciąż są dopracowywane — opisane jako w toku, a nie jako ukończone.

Powiązane dokumenty

Dokumentacja jako produkt — szersza dyscyplina jakości, której częścią jest ten system cytowania.
Krajobraz standardów — standardy, na które wskazują te cytowania, oraz sposób, w jaki klauzula staje się udokumentowanym zachowaniem.
Piramida testów NextPDF — co oznacza dowód oparty na testach, gdy strona opiera się na tej podstawie zamiast na obecnej.

Słownik

Dyscyplina cytowania — zbiór reguł określających, jak twierdzenie Insider_ wiąże się ze swoim źródłem: parafrazuj, wskaż dokładną klauzulę, nigdy nie cytuj licencjonowanego standardu.
Parafraza — przeformułowanie wymagania własnym językiem NextPDF, spójnym ze słownikiem; test zrozumienia, który zastępuje cytowanie.
Odniesienie do klauzuli — dokładna klauzula lub sekcja, na której opiera się parafraza, zapisana tak, by recenzent mógł ją otworzyć i zweryfikować przeformułowanie.
Twierdzenie oparte na standardzie — twierdzenie zakotwiczone w przywołanej, sparafrazowanej klauzuli nazwanego standardu, w odróżnieniu od twierdzenia opartego na kodzie silnika, teście, pomiarze lub rozumowaniu redakcyjnym.
Nierozwiązane cytowanie — twierdzenie, którego nie da się jeszcze powiązać z klauzulą, którą autor przeczytał; zachowane, oznaczone jako otwarte i wstrzymane przed publikacją zamiast sfabrykowane.