Дисциплина цитирования

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

Кратко

Это та страница, на которую ссылаются все остальные страницы Insider_, когда объясняют, как они цитируют стандарт. Она объясняет, почему эта документация перефразирует спецификации, а не цитирует их, как утверждение называет стандарт и точный пункт, на который оно опирается, и что именно обещает чистое цитирование, а чего нет.

Она написана для опытного инженера, который, прежде чем доверять утверждению, хочет знать правила, по которым оно сформулировано, — и это разумное требование.

Почему это важно

Все остальные страницы Insider_ содержат утверждения и привязывают их к названному стандарту и пункту. Такое цитирование имеет смысл лишь в том случае, если стоящая за ним дисциплина явно определена. Если “подкреплено стандартом” может означать что угодно — от “я внимательно прочитал спецификацию” до “я примерно помню, что в ней говорилось”, — цитирование становится украшением.

Есть и более жёсткое ограничение. Многие из документов, которым следует NextPDF, — спецификации ISO, ETSI и подобные — являются лицензируемыми. Воспроизведение их текста, в любом объёме, не допускается. Поэтому дисциплина должна решать сразу две задачи: сделать утверждение прослеживаемым до его источника, не воспроизводя этот источник. Ответ на обе задачи — точное цитирование и верное перефразирование, и эта страница является их спецификацией.

Краткая версия

Insider_ перефразирует стандарты и никогда не цитирует лицензируемые стандарты. Утверждение называет стандарт и точный пункт; оно не воспроизводит формулировки стандарта.
Перефразирование — не обходной приём; это проверка на понимание. Изложение требования собственным языком NextPDF заставляет автора понять его и сохраняет терминологию согласованной с глоссарием Spec: ISO/IEC/IEEE 26514, §8.
Каждое подкреплённое стандартом утверждение называет конкретный пункт или раздел, а не документ целиком, чтобы следующий рецензент мог открыть этот пункт и сверить с ним перефразирование.
Цитирование указывает вид источника, на который оно опирается, — пункт, код движка, тест, измерение, — так что завышенное утверждение видно с первого взгляда.
Когда утверждение не удаётся привязать к пункту, который автор действительно прочитал, оно не подделывается. Оно сохраняется, помечается как неразрешённое, а страница остаётся неопубликованной — это задокументированный протокол, а не импровизация.

Как к этому подходит NextPDF

Перефразирование, а не цитирование

Строжайшее правило в иерархии стиля NextPDF имеет приоритет над любым более общим руководством: никакого дословного текста от лицензирующей организации по стандартизации, каким бы коротким ни был фрагмент. Вместо этого страница называет стандарт и пункт и перефразирует требование собственным языком.

Обычно об этом говорят как о лицензионном ограничении, и оно действительно таково. Но полезнее посмотреть на него редакторски. Дословная цитата доказывает лишь то, что вы умеете копировать. Точное перефразирование показывает, что вы поняли пункт достаточно хорошо, чтобы изложить его заново без изменения смысла. Кроме того, оно помогает предложению оставаться в согласованной терминологии NextPDF и не менять регистр посреди страницы, чего и требует модель качества документации Spec: ISO/IEC/IEEE 26514, §8. Ясность языка оценивается по тому, может ли читатель найти, понять и использовать содержимое, а не по тому, воспроизводит ли текст источник Spec: ISO 24495-1, §Introduction; перефразирование служит этой цели, а цитирование — нет.

Утверждение называет пункт, а не только документ

Механизм, который делает перефразирование проверяемым, — это точность. Каждое подкреплённое стандартом утверждение называет точный пункт или раздел, на который оно опирается, — например, ISO 32000-2 §6, — а не только документ. Рецензенту не нужно доверять памяти автора; он открывает этот пункт и сравнивает его с переформулировкой. Ссылка на пункт — связующее звено между непроцитируемым источником и проверяемым утверждением. Она указывает, где смотреть, не передавая текст самого источника.

Цитирование говорит, какого вида этот источник

Цитирование отвечает на вопрос “откуда”. Оно должно ответить и на вопрос “какого вида”. Сказать, что утверждение опирается на пункт стандарта, — это иное обещание, чем сказать, что оно опирается на собственный код движка, на тест или на измерение. NextPDF держит эти виды раздельно, чтобы читатель мог их взвесить: код и тесты стоят выше поведения во время выполнения, время выполнения — выше метаданных, а метаданные — выше текста. Редакторская страница, как эта, не притворяется подкреплённой кодом.

Вид источника	Что он обещает	Чего он не обещает
Подкреплённый кодом	Утверждение проверяется по исходному коду движка или по исполняемому примеру	Что этого требует стандарт
Подкреплённый стандартом	Утверждение привязано к процитированному, перефразированному пункту	Что код сейчас реализует это без исключений
Подкреплённый тестом	Тест в наборе фиксирует поведение	Показатель производительности
Подкреплённый бенчмарком	Измерение по заявленной методике подтверждает показатель	Такой же показатель на вашем оборудовании
Подкреплённый артефактом	Созданный артефакт (результат сборки, отчёт) демонстрирует это	Требование стандарта
Проектный принцип	Осознанное, аргументированное проектное решение	Эмпирическое измерение
Редакторский	Обоснованное объяснение, упорядочивающее другой материал	Новую самостоятельную гарантию поведения
Смешанный	Страница сочетает разные основания и указывает конкретное основание для каждого утверждения	Единое чистое основание

Эта страница редакторская: она не утверждает никакого собственного поведения движка. Она объясняет дисциплину, на которую опираются цитаты других страниц. Это честное для неё основание, и объявить его — значит применить дисциплину к самой себе.

Когда источник не удаётся прочитать

Доступ к стандарту не всегда мгновенный — лицензируемую спецификацию автору, возможно, ещё предстоит получить, а пункт может потребовать повторного прочтения, прежде чем его смысл станет ясен. Целостность дисциплины проявляется в том, что происходит в этом случае. Автор не гадает. Утверждение, которое пока не удаётся привязать к пункту, действительно прочитанному автором, сохраняется, привязывается к материалу внутри репозитория и к ссылке на стандарт, которую объявляет сам код, явно помечается как неразрешённое, а страница остаётся неопубликованной, пока пункт не будет процитирован корректно.

Запрещённые действия перечислены и поддаются проверке: номер пункта, выдуманный для видимости точности, цитата, оформленная так, будто её прочитали, хотя она написана по памяти, или негласное удаление утверждения, чтобы уклониться от цитирования. Корректно помеченное открытое цитирование в черновике — это долг с пометкой, а не дефект. Офлайновая детерминированная проверка обеспечивает именно это различие.

Размещение стандарта и пункта вверху каждой страницы, до первого слова основного текста, — это решение из области человеческого фактора, а не стилистики. Оно позволяет читателю судить о виде источника через узнавание, а не дочитывать до конца и только потом делать вывод, — по той же причине структура разделов фиксирована, а ссылки на связанную документацию написаны так, что их назначение ясно из самого текста ссылки. Цитирование заслуживает доверия только в том случае, если стандарт, на который оно опирается, — первое, что вы видите, а не последнее, что вы реконструируете.

Практический пример

Дисциплина конкретна: это структура front-matter citations страницы. Каждая запись привязывает утверждение к его пункту.

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"

Поля quote нет — намеренно. Поле topic — это собственная переформулировка NextPDF. Поля spec и clause — это способ, которым рецензент возвращается к точному источнику, чтобы проверить эту переформулировку. Запись несёт указатель на пункт, а не его текст.

Распространённое заблуждение

Ловушка в том, чтобы прочитать “перефразируй, а не цитируй” как уклончивость — способ выглядеть авторитетно, ни к чему не обязываясь. Всё наоборот. Цитата ни к чему не обязывает; она заимствует чужие слова. Перефразирование с привязкой к источнику заставляет автора дать формулировку, которую рецензент может опровергнуть по пункту. Дисциплина делает утверждения более ответственными, а не менее.

Вторая ловушка — относиться к “редакторскому” уровню как к более слабой степени “подкреплённого стандартом”. Это вообще не степень; это другой вид. Редакторская страница, как эта, упорядочивает и объясняет другой материал. Она помечена правильно. И именно эта пометка важна: система работает потому, что страница сообщает вам, на какой вид источника она опирается, прежде чем вы решите, какой вес ему придать.

Ограничения и границы

Эта страница задаёт дисциплину цитирования; она не является ни таблицей стилей, ни кодом шлюза. Авторитетные артефакты находятся внутри репозитория (docs/style/nextpdf-overrides.md §5 и скрипты composer.jsondocs:*) и имеют приоритет над любым изложением здесь, если они расходятся. Она не утверждает никакого поведения движка.

Дисциплина связывает утверждение, а не вывод читателя. Точно процитированное перефразирование сообщает вам, чего требует пункт. Подходит ли прочтение NextPDF для вашего обязательства, — по-прежнему ваше решение; именно поэтому поведенческие страницы несут также цитаты, подкреплённые кодом или тестами, а не только стандартом. Соблюдение обеспечивается частично, и это прямо признано: офлайновая проверка работает, а верификаторы дословных цитат и живых ссылок подключены, тогда как их исчерпывающие исполнители ещё дорабатываются — это заявлено как незавершённое, а не как готовое.

Связанная документация

Документация как продукт — более широкая дисциплина качества, частью которой является эта система цитирования.
Ландшафт стандартов — стандарты, на которые указывают эти ссылки, и как пункт становится задокументированным поведением.
Пирамида тестирования NextPDF — что означает подкреплённое тестами доказательство, когда страница опирается на это основание вместо данного.

Глоссарий

Дисциплина цитирования — свод правил, определяющий, как утверждение Insider_ привязывается к своему источнику: перефразируй, называй точный пункт, никогда не цитируй лицензируемый стандарт.
Перефразирование — изложение требования собственным, согласованным с глоссарием языком NextPDF; проверка на понимание, заменяющая цитирование.
Ссылка на пункт — точный пункт или раздел, на который опирается перефразирование, записанный так, чтобы рецензент мог открыть его и проверить переформулировку.
Подкреплённое стандартом утверждение — утверждение, привязанное к процитированному, перефразированному пункту названного стандарта, в отличие от утверждения, опирающегося на код движка, тест, измерение или редакторское рассуждение.
Неразрешённая ссылка — утверждение, которое пока не удаётся привязать к пункту, прочитанному автором; оно сохранено, помечено как открытое и не допущено к публикации, а не подделано.