Open Manuscript Initiative Архитектурен одит

Статус на документа

Поле	Стойност
Вид документ	Одит на управлението/архитектурата
Статус	Чернова
Версия	0.1
Обхват	Нормативна и техническа документация на английски език
Целева аудитория	Редактори на спецификации, разработчици, рецензенти и сътрудници

Обобщение

Репозиториумът „Open Manuscript Initiative“ вече съдържа основите на един солиден стандарт за научни документи. Репозиториумът включва концептуални основи, семантични модели, модели на работни процеси, спецификации за обмен, концепции за публикуване и материали, насочени към практическото приложение.

Основната слабост вече не е липсата на идеи. Тя е архитектурната фрагментация.

Документацията се е разраствала постепенно и в момента няколко проблема ограничават използването ѝ като цялостен набор от спецификации:

• в навигацията на уебсайта се показва само малка част от наличните документи;
• идентификаторите на спецификациите, версиите и състоянията в жизнения цикъл са несъвместими;
• връзката между нормативните изисквания и информативните насоки не винаги е ясна;
• някои документи се припокриват или дублират;
• зависимостите между моделите рядко се декларират;
• много от необходимите модели остават имплицитни, вместо да бъдат формално дефинирани;
• връзката между стандарта „OMI“ и „Open Manuscript Studio“ не е систематично документирана;
• Все още няма канонична схема и рамка за съответствие, които да обвързват текстовите спецификации с поведение, което може да бъде проверено от машина.

Препоръчителният следващ етап е програма за контролирано преструктуриране на спецификациите. Наличният материал трябва да бъде запазен, когато е валиден, но да бъде преорганизиран в стабилна йерархия с постоянни идентификатори, общи метаданни, изрично посочени зависимости, статус на внедряване и нормативни схеми.

Цели на одита

Настоящият одит има пет цели:

1. да се направи опис на наличната документация;
2. да разграничава съществуващия, частичния, дублирания, остарелия и липсващия материал;
3. да се определи целевата архитектура на спецификацията;
4. да се определят задачите, които възпрепятстват разработката на „OMI“ 1.0;
5. да се установи безопасна последователност на миграцията, която да не нарушава публикуваните връзки и текущата работа по внедряването.

Принципи на одита

При извършването на одита се прилагат следните принципи.

Запазване на полезния труд

Съществуващите документи не трябва да се изхвърлят само защото структурата им е непоследователна. Валидните концепции трябва да бъдат обединени в канонични спецификации.

Разделяне на семантиката от реализацията

Спецификацията „OMI“ определя съвместими научни обекти и модели на поведение. Open Manuscript Studio представя една от възможните реализации, но не трябва да се приема като нормативно определение на стандарта.

Предпочитайте стабилни идентификатори пред пътеки към файлове

Идентификаторът на спецификацията трябва да остава непроменен, дори ако името на файла, заглавието или категорията за навигация се променят.

Осигурете възможност за тестване на съответствието

Нормативната проза в крайна сметка трябва да съответства на схеми, правила за валидиране, примери и тестове за съответствие.

Преструктурирайте кода преди превода

Пакетът от спецификации на английски език трябва да бъде финализиран, преди да бъдат изготвени пълните преводи на унгарски и немски език.

Актуален списък на документацията

Настоящото хранилище съдържа материали, разпределени в няколко функционални групи.

Основи

Сред известните основополагащи документи са:

• Визия
• Основни принципи
• Карта на архитектурата
• Модел на научния обект

Тези документи определят целта и общата структура на OMI. Те са от съществено значение, но техният нормативен статут и взаимовръзките им изискват изясняване.

Основни семантични спецификации

Настоящият основен материал включва:

• Модел на документа
• Модел на метаданните
• Модел „Анкор“
• Модел за анотиране
• Модел за цитиране
• Модел на библиографска записка
• Архитектура на справочната библиотека и регистъра

Взети заедно, те описват съществена част от семантичния модел на ръкописа.

Спецификации на работния поток и научния процес

Наличният или частично разработен материал включва:

• Модел за преглед
• Модел на публикуване
• концепции за сътрудничество, въплътени в „Open Manuscript Studio“
• преводачески концепции, заложени в многоезичната архитектура

Моделът за преглед съществува като документ, докато сътрудничеството и преводът изискват официални самостоятелни спецификации.

Спецификации за обмен и опаковане

Съществуващите документи включват:

• Формат на файла
• Архитектура на контейнерите
• API

Те осигуряват първоначална основа за обмен и интеграция, но изискват съгласуване с каноничния обектен модел и бъдещата схема „JSON“.

Спецификации за разширяемост

Съществуващите документи включват:

• Архитектура на плъгините

Все още е необходим модел на възможностите, за да се определи как реализациите посочват коя поддръжка е опционална и коя е задължителна.

Материали за управление

Дейностите в областта на управлението понастоящем включват или се планира да включват:

• OMI Устав
• План за развитие на „OMI“ 1.0
• този архитектурен одит
• Животният цикъл на спецификацията
• Политика за версиите
• Ръководство за стил на спецификациите
• Терминология и речник

Резултати

1. Навигацията показва само малка част от набора от спецификации

В момента страничната лента на уебсайта показва само малка част от документите, съхранявани в хранилището. До няколко съществуващи спецификации не може да се стигне чрез обичайната навигация в документацията.

Това създава три риска:

• авторът може да предположи, че скритите документи са остарели;
• читателите могат да получат непълна представа за архитектурата;
• може да възникне дублиране на работата, тъй като е трудно да се открие вече съществуващ материал.

Необходимо действие

След прегледа на съдържанието страничната лента трябва да бъде преструктурирана въз основа на стабилни архитектурни категории, а не като обикновен списък с файлове.

2. Моделът на научния обект е дублиран

Хранилището съдържа две пътеки на модела „Scholarly Object Model“:

• docs/specifications/scholarly-object-model.md
• docs/specifications/core/scholarly-object-model.md

Съществуването на два документа, които на пръв поглед изглеждат канонични, създава неяснота относно това кой модел определя начина на реализация.

Необходимо действие

Двата документа трябва да бъдат сравнени раздел по раздел. Валидното съдържание трябва да бъде обединено в един каноничен документ на адрес OMI-SPEC-001. Премахнатият адрес трябва или да пренасочва към каноничната страница, или да съдържа изрично уведомление за замяната, докато пренасочванията не бъдат надеждно настроени.

3. Идентификаторите на спецификациите са непълни и потенциално нестабилни

В някои документи вече се използват идентификатори като OMI-SPEC-005, докато в други – не. При липса на регистър е възможно повторно използване на идентификатори или случайно преномериране.

Необходимо действие

Създайте регистър на спецификациите, в който идентификаторите се присвояват трайно. Идентификаторите никога не трябва да се използват повторно без предупреждение, дори когато дадена спецификация бъде оттеглена.

Временна поредица е:

Идентификатор	Спецификация	Текущо състояние
OMI-SPEC-001	Модел на научния обект	Съществува, дублира се; необходима е консолидация
OMI-SPEC-002	Модел на документа	Съществува; изисква преглед
OMI-SPEC-003	Модел на метаданни	Съществува; изисква преглед
OMI-SPEC-004	Модел „Anchor“	Съществува; необходим преглед
OMI-SPEC-005	Модел за цитиране	Съществува; в процес на преработка
OMI-SPEC-006	Модел на библиографски запис	Изготвен проект
OMI-SPEC-007	Архитектура на справочната библиотека и регистъра	Изготвен проект
OMI-SPEC-008	Модел за валидиране	Липсва
OMI-SPEC-009	Модел за версиониране и промени	Липсва
OMI-SPEC-010	Модел за идентичност и сътрудници	Липсва
OMI-SPEC-011	Модел за сътрудничество и разрешения	Липсва
OMI-SPEC-012	Модел на превода	Липсва
OMI-SPEC-013	Модел на профил за визуализация и публикуване	Липсва
OMI-SPEC-014	Модел за внос и износ	Липсва
OMI-SPEC-015	Модел на възможностите и съответствието	Липсва

Тази номерация е временна, докато регистърът не бъде официално приет.

4. Състоянията от жизнения цикъл не се регулират

В документите се използват обозначения като „Draft“, но значението на тези обозначения не е дефинирано. Поради това не е ясно дали даден проект представлява проучвателна проза, вариант, подходящ за реализация, или документ, който очаква редакционна проверка.

Необходимо действие

Въведете единен жизнен цикъл:

1. Проучвателен
2. Чернова
3. Кандидат за преглед
4. Кандидат за изпълнение
5. Стабилен
6. Остаряло
7. Отменено

Всяка държава трябва да има критерии за влизане и излизане.

5. Нормативното и информативното съдържание са смесени

В редица документи са съчетани архитектурни изисквания, примери, идеи за бъдещето, обяснителен текст и предложения за реализация, без да се посочва източникът им.

Необходимо действие

Всяка спецификация трябва ясно да разграничава:

• нормативни изисквания;
• изчерпателно обяснение;
• незадължителни примери;
• отложена бъдеща работа;
• бележки за внедряването.

В нормативните изисквания трябва да се използват последователни термини като „ТРЯБВА“, „НЕ ТРЯБВА“, „СЛЕДВА“, „НЕ СЛЕДВА“ и „МОЖЕ“, чиито значения са определени в ръководството за стил на спецификацията.

6. Зависимостите са имплицитни

Наборът от модели образува граф на зависимостите, но тези зависимости не се регистрират систематично.

Например:

• Моделът за цитиране зависи от модела на научния обект, модела на анкора и модела на библиографския запис;
• Моделът „Анотация“ зависи от модела „Анкер“;
• Моделът за преглед зависи от модела за анотации, модела за идентичност и съавторство, както и от модела за сътрудничество и разрешения;
• Моделът на публикуване зависи от модела на документа, модела на метаданните, модела на цитирането, профилите за визуализация и модела за валидиране.

Необходимо действие

Всяка спецификация трябва да съдържа следното:

• Зависи от
• Използва се от
• Свързани технически характеристики
• Заменя
• Заменено от

Регистърът със спецификации, подходящ за машинно четене, може по-късно да генерира тези взаимоотношения автоматично.

7. Посочва се валидирането, но то не е дефинирано централизирано

В много документи се споменава валидирането, но няма общ модел за валидиране, който да определя класовете грешки, етапите на валидиране, отчетите, профилите или нивата на съответствие.

Необходимо действие

Създайте „OMI-SPEC-008: Validation Model“, в който да се разгледат следните теми:

• валидиране на схемата;
• структурна валидация;
• проверка на метаданните;
• проверка на валидността на идентификатора;
• библиографска валидация;
• целостност между обектите;
• проверка на профила за публикации;
• грешки, предупреждения и информационни съобщения;
• отчети за валидиране, подходящи за машинно четене;
• разширяеми идентификатори на правила за валидиране.

8. Липсват версиониране и семантика на промените

И хранилището, и Studio предполагат наличието на научни обекти с версии, но няма нормативен модел, който да дефинира ревизии, разклонения, одобрени промени, състояния на публикуване или произход на ниво обект.

Необходимо действие

Създайте „OMI-SPEC-009: Versioning and Change Model“, който да обхваща:

• версии на ръкописа;
• ревизии на обекти;
• операции по промяна;
• авторство и времеви отметки;
• сравнения и разлики;
• приети и отхвърлени промени;
• непроменими публикувани моментални снимки;
• миграция между версии на схемата.

9. Семантиката на идентичността и на участниците е непълна

Метаданните могат да посочват имената на участниците, но е необходим модел за многократно използване на идентичността за лица, организации, идентификатори, принадлежности, роли и исторически форми на имената.

Необходимо действие

Създайте „OMI-SPEC-010: Identity and Contributor Model“, който да обхваща:

• лица и организации;
• ORCID и ROR;
• местни идентичности;
• имена и варианти на имена;
• членства със срокове на валидност;
• ред на авторите;
• CRediT и разширяеми роли;
• статус на автор за кореспонденция;
• редакторски и преводачески приноси.

10. Концепциите за сътрудничество са заложени в кода, но не и в стандарта

Open Manuscript Studio вече съдържа роли в работната среда и покани, но тези понятия все още не са формализирани като семантика, независима от конкретната реализация OMI.

Необходимо действие

Създайте „OMI-SPEC-011: Collaboration and Permission Model“, в който да се обхванат следните теми:

• работни пространства;
• членство;
• ролите „собственик“, „редактор“, „съавтор“, „рецензент“, „преводач“ и „зрител“;
• покани;
• обхвати на разрешенията;
• достъп на ниво обект и на ниво секция;
• събития, свързани с одит;
• разделяне на автентичността от преносимостта на ръкописа.

11. Многоезичните ръкописи изискват преводачески модел

Уебсайтът и Studio поддържат няколко езика, но връзката между оригиналния текст и преведените научни обекти все още не е описана по нормативен начин.

Необходимо действие

Създайте „OMI-SPEC-012: Translation Model“, в което да се разгледат следните теми:

• изходен и целеви език;
• подредени обекти и опорни точки;
• статус на превода;
• откриване на остарели преводи;
• бележки на преводача;
• няколко целеви езика;
• частични преводи;
• публикуване на паралелни и независими езикови версии.

12. Профилите за визуализация и публикуване не са достатъчно разграничени

Архитектурата правилно разглежда семантиката и представянето като отделни слоеве, но е необходим формален профилен модел, за да се определи как списанията и издателите съпоставят семантичното съдържание с крайните продукти.

Необходимо действие

Създайте „OMI-SPEC-013: Rendering and Publication Profile Model“, в който да се обхванат следните теми:

• профили на публикации;
• цели за продукция;
• отбелязване на цитати и излагане на бележки;
• правила за типография и оформление;
• задължителни и незадължителни раздели;
• разширения за списания и издатели;
• достъпни резултати от HTML, PDF, EPUB и XML;
• детерминистични входни данни за рендериране.

13. Поведението при импорта и експорта не е достатъчно подробно описано

Форматът на файла и моделът на публикуване сами по себе си не определят качеството на преобразуването, неподдържаното съдържание, броя на циклите на преобразуване или отчетите за преобразуване.

Необходимо действие

Създайте „OMI-SPEC-014: Import and Export Model“, в която се разглеждат следните теми:

• DOCX, Markdown, JATS, HTML, CSL JSON, BibTeX и RIS преобразувания;
• преобразувания без загуба и със загуба;
• предупреждения за преобразуване;
• неподдържани елементи;
• произход на източника;
• очаквания за пътуването в двете посоки;
• съхранение на разширенията;
• профили за експорт.

14. Липсват нива на съответствие и обявени възможности

Не всяка реализация ще поддържа всеки опционален модел или изход. Необходим е общ механизъм за деклариране на поддръжката, без това да води до фрагментиране на стандарта.

Необходимо действие

Създайте документ „OMI-SPEC-015: Capability and Conformance Model“, който да обхваща:

• съответствие с основните изисквания;
• допълнителни функции;
• съответствие на профила;
• декларации на разширения;
• версии на схемата;
• възможности за внос и износ;
• възможности за валидиране;
• манифести за внедряване, които могат да се четат от машина.

15. Спецификациите на прозата все още не са обвързани с канонична схема

OMI не може да се постигне надеждна оперативна съвместимост, докато структурата на данните съществува само в текстова форма и чрез примери.

Необходимо действие

Разработете набор от канонични схеми с версии, като се започне със схемата „JSON“. Работата по схемите трябва да включва:

• стабилни идентификатори на схеми;
• определения за многократна употреба;
• режими на валидиране – строг и отчитащ разширенията;
• кратки примери;
• пълни примери;
• невалидни съоръжения;
• приспособления за миграция;
• автоматизирани тестове за съответствие.

16. Статусът на изпълнението не се вижда

Читателите не могат лесно да преценят дали даден модел е концептуален, частично реализиран или се изпълнява чрез производствен код.

Необходимо действие

Създайте страница „Статус на внедряването“ с етикети, основани на факти:

• Не е започнало
• Проучвателен
• Частично
• Реализирано експериментално
• Внедрено в еталонния софтуер
• Проверено за съответствие

Матрицата не трябва да претендира за съответствие, когато съществува само функция с подобно име.

17. Терминологията изисква централизирано управление

Термини като „ръкопис“, „документ“, „научен обект“, „препратка“, „цитиране“, „библиографска записка“, „анотация“, „редакция“ и „публикация“ могат да се тълкуват по различен начин в различните дисциплини и софтуерни системи.

Необходимо действие

Създайте документ с нормативна терминология и речник. Спецификациите трябва да съдържат препратки към общоприети определения, а не да предефинират основните термини по непоследователен начин.

Архитектура на целевата документация

Препоръчителната структура на документацията е:

Introduction
├── Vision
├── Core Principles
└── Architecture Map

Foundations
├── Terminology and Glossary
├── Scholarly Object Model
├── Document Model
├── Metadata Model
└── Identity and Contributor Model

Editing and Collaboration
├── Anchor Model
├── Annotation Model
├── Review Model
├── Collaboration and Permission Model
├── Versioning and Change Model
└── Translation Model

Bibliography and Citations
├── Bibliographic Record Model
├── Citation Model
├── Reference Library and Registry Architecture
└── Citation Graph (future)

Publishing and Validation
├── Validation Model
├── Rendering and Publication Profile Model
└── Publishing Model

Exchange and Packaging
├── File Format
├── Container Architecture
├── Import and Export Model
└── API

Extensibility and Conformance
├── Plugin Architecture
├── Capability and Conformance Model
└── Implementation Status

Governance
├── OMI Charter
├── Roadmap to OMI 1.0
├── Architecture Audit
├── Specification Registry
├── Specification Lifecycle
├── Versioning Policy
├── Specification Style Guide
└── Translation Policy

Метаданни за стандартната спецификация

Всяка нормативна спецификация трябва да съдържа стандартен блок с метаданни.

Задължителни полета:

Identifier
Title
Version
Status
Document type
Editors
Last updated
Normative language
Depends on
Used by
Related specifications
Implementation status
Schema reference
Supersedes
Superseded by

Docusaurus Встъпителната част трябва да улеснява навигацията и представянето, но метаданните от спецификацията „stable“ също трябва да бъдат ясно видими в документа.

Стратегия за преструктуриране на хранилището

Преместването на голям файл не трябва да се извършва, докато не бъдат одобрени одитът на съдържанието и регистърът на идентификаторите. Преждевременното преместване би довело до неработещи връзки и конфликти при сливането, без да се разреши концептуалната двусмисленост.

Препоръчителната последователност е:

Етап 1 — Основи на управлението

• да се обедини Уставът;
• да се обедини пътната карта с „OMI“ 1.0;
• да приеме този архитектурен одит;
• да създаде документите „Животният цикъл на спецификацията“, „Политика за версиите“, „Наръчник за стил“ и „Терминология“.

Етап 2 — Каноничен инвентар

• да присвоява постоянни идентификатори;
• да се идентифицират каноничните и отменените документи;
• да се консолидира дублираният модел на научните обекти;
• пренасочвания на документи и запазени псевдоними.

Фаза 3 — Рефакторинг на навигацията

• да преорганизирате страничната лента;
• да се анализират съществуващите спецификации;
• добавете етикети със статус, където е уместно;
• да се запазват стабилни публични URL адреси, където това е възможно.

Фаза 4 — Липсващи основни модели

• Модел за валидиране;
• Модел за версиониране и промени;
• Модел на идентичността и сътрудниците;
• Модел на сътрудничество и разрешения;
• Модел за превод.

Етап 5 — Публикуване и приключване на обмена

• Модел на профила за рендиране и публикуване;
• Модел за внос и износ;
• Модел на възможностите и съответствието;
• да се преразгледат и хармонизират форматът на файловете, архитектурата на контейнера, „API“, моделът на публикуване и архитектурата на плъгините.

Етап 6 — Схема и съответствие

• канонична схема „JSON“;
• примерен корпус;
• невалидни съоръжения;
• автоматизирана проверка;
• проявяват се възможности за внедряване;
• набор от тестове за съответствие.

Етап 7 — Интернационализация

• да финализираме английската версия „Release Candidate“;
• създаване на каталози с преводи и копия на документи;
• превод на унгарски и немски;
• да публикува информация за състоянието на превода и предупреждения за разминавания;
• да се въведе процедура за синхронизиране на последващите промени.

Класификация по приоритет

От решаващо значение преди версия 1.0 на „OMI“

• каноничен модел на научни обекти;
• регистър на спецификациите и техният жизнен цикъл;
• Съгласувани модели за документи, метаданни, препратки, анотации, цитиране и библиографски данни;
• Модел за валидиране;
• Модел за версиониране и промени;
• Модел на идентичността и сътрудниците;
• канонична схема „JSON“;
• определения за съответствие;
• пълни нормативни примери.

Висок приоритет

• Модел на сътрудничество и разрешения;
• Модел за превод;
• Модел на профила за рендиране и публикуване;
• Модел за внос и износ;
• матрица за състоянието на изпълнението;
• терминология и речник.

Важно, но може да последва кандидат за първоначално внедряване

• Графика на цитиранията;
• усъвършенствани протоколи за разпределен регистър;
• профили по конкретни дисциплини;
• регистър за официални разширения;
• допълнителни официални преводи, освен на унгарски и немски език.

Рискове

Разширяване на обхвата

OMI обхваща широк научен цикъл. Без критерии за поетапно пускане проектът би могъл да отложи за неопределено време създаването на стабилна основна версия.

Мерки за смекчаване: да се определи минимален ядрен набор от изисквания за съответствие с OMI 1.0, а допълнителните възможности да се включат в профилите.

Разлики между документацията и кода

Разработката в студиото може да напредва по-бързо от описанията в спецификациите.

Мерки за ограничаване на риска: да се изискват актуализации на състоянието на внедряването и тестови набори за проверка на съответствието при значителни промени в модела.

Нестабилност на идентификаторите

Преименуването на документи преди въвеждането на регистър може да направи външните позовавания ненадеждни.

Мерки за смекчаване: първо присвоявайте постоянни идентификатори и запазвайте пренасочванията или псевдонимите.

Отклонение при превода

Преводът на нестабилни спецификации би довел до увеличаване на обема на работата по поддръжката и би създал противоречиви езикови версии.

Мерки за намаляване на риска: превеждайте едва след като вариантът за преглед на английски е финализиран и ясно маркирайте преведените версии.

Прекомерна централизация на регистрите

Архитектурата на справочна библиотека би могла случайно да подскаже, че „OMI“ изисква наличието на един-единствен централен библиографски авторитет.

Мерки за смекчаване на риска: да се запазят федеративното разрешаване, проследяемостта на източника, офлайн записите и независимостта на внедряването като изрични архитектурни принципи.

Критерии за завършване на програмата за рефакторинг

Фазата на рефакторинг на архитектурата приключва, когато:

• всяка активна спецификация има едно канонично местоположение;
• всяка нормативна спецификация има постоянен идентификатор;
• приети са състоянията на жизнения цикъл и правилата за версиите;
• страничната лента представя цялостната преработена архитектура;
• декларират се зависимостите и свързаните с тях спецификации;
• дублиращите се спецификации се обединяват;
• изготвят се липсващите основни модели;
• съществуват канонични схеми и примери;
• състоянието на изпълнението се документира без необосновани твърдения;
• Документацията на английски език достига до кандидат за преглед, подходящ за превод.

Препоръчителни документи, които следва да се прочетат веднага след това

След този одит следващите документи за управление трябва да бъдат изготвени в следния ред:

1. Животният цикъл на спецификацията
2. Политика за версиониране на спецификациите
3. Ръководство за стил на спецификациите
4. Терминология и речник
5. Регистър на спецификациите

След като те бъдат приети, консолидирането на дублиращите се модели и пълното преструктуриране на страничната лента могат да продължат безпроблемно.

Заключение

„Open Manuscript Initiative“ вече е надхвърлила рамките на проучвателна колекция от идеи. Тя вече съдържа основата на цялостна научна архитектура на ръкописа.

Следващото предизвикателство е дисциплинираното консолидиране.

За да бъде стабилна, платформата „OMI“ 1.0 се нуждае от контролиран набор от спецификации, а не просто от допълнителни документи. Поради това непосредствените архитектурни приоритети са: постоянни идентификатори, ясно определени състояния на жизнения цикъл, канонични модели, схеми, подлежащи на машинно проверяване, декларирани зависимости и прозрачен статус на имплементацията.

Този одит представя работния план за този преход.