Open Manuscript Initiative Архитектура на документацията

Метаданни на документа

Поле	Стойност
Тип документ	Политика за управление
Статус	Чернова
Версия	0.1.0
Нормативна терминология	Английски
Важи за	Документация на уебсайта OMI, спецификации, документи за управление, генерирани страници с категории и преводи

1. Цел

Настоящият документ определя информационната архитектура на пакета от документация на „Open Manuscript Initiative“.

В него се постановява:

• категориите на документацията на най-високо ниво;
• стандартното местоположение на всеки активен документ;
• връзката между концептуалните, нормативните, свързаните с прилагането и свързаните с управлението аспекти;
• правилата, използвани от страничната лента „Docusaurus“;
• поведение на целевата страница по категории;
• обработката на стари, отменени и предназначени единствено за миграция страници;
• Изисквания за стабилност на URL адресите и локализация;
• критерии за поддържане и преглед при бъдещи промени в документацията.

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

Тези аудитории включват:

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

2. Архитектурни принципи

Пакетът с документация „OMI“ се придържа към тези принципи.

2.1 Едно канонично местоположение

Всеки активен документ ТРЯБВА да има един каноничен изходен файл и едно канонично място в страничната лента.

Един документ МОЖЕ да бъде свързан с други страници, но НЕ ТРЯБВА да бъде регистриран като дубликат в същата странична лента.

Това правило предотвратява:

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

2.2 Архитектурата преди хронологията

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

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

2.3 Стабилни обществени маршрути

При рефакторирането на документацията СЛЕДВА да се запазват съществуващите публични URL адреси, когато това е възможно.

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

Когато даден маршрут трябва да бъде променен, старият маршрут ТРЯБВА да остане достъпен чрез:

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

2.4 Разграничаване на нормативния и обяснителния материал

Страничната лента ТРЯБВА да прави разграничение между:

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

Концептуалните въведения НЕ ТРЯБВА да заменят без предупреждение нормативните изисквания.

Нормативните спецификации ТРЯБВА да посочват изрично своите зависимости и състоянието на жизнения си цикъл.

2.5 Пълна откриваемост

Всеки активен документ, свързан със спецификацията и управлението на „OMI“, предназначен за обществено обсъждане, ТРЯБВА да бъде достъпен от основната странична лента.

Старите страници за миграция, вътрешните бележки, генерираните артефакти и остарелите чернови МОГАТ да останат извън страничната лента.

2.6 Постепенно разкриване

Навигацията ТРЯБВА да позволява на читателите да преминават от общи понятия към подробни изисквания.

Очакваното развитие е:

Vision
  ↓
Architecture overview
  ↓
Foundational concepts
  ↓
Core semantic models
  ↓
Workflow and publishing models
  ↓
Platform and exchange specifications
  ↓
Governance and standards process

От читателите не се изисква да спазват тази последователност, но редът ТРЯБВА да отразява структурата на зависимостите.

3. Архитектура на навигацията на най-високо ниво

Страничната лента с документация на „OMI“ съдържа шест категории от най-високо ниво.

Introduction
Foundations
Core Semantic Specifications
Scholarly Workflow and Publishing
Platform and Exchange
Governance

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

4. Въведение

В категорията „Въведение“ се обяснява защо съществува OMI и как е организирана цялостната архитектура.

Съдържа:

1. Визия
2. Общ преглед на архитектурата

Общият преглед на архитектурата се съдържа в съществуващия документ „Архитектурна карта“. Наименованието в страничната лента МОЖЕ да бъде опростено, без да се променят заглавието на документа или пътят до изходния файл.

Категорията „Въведение“ има обяснителен характер. Тя не определя подробни изисквания за съответствие, освен в случаите, когато включен документ изрично посочва, че съдържанието му е нормативно.

5. Основи

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

Съдържа:

1. OMI-SPEC-000 — Основни принципи
2. OMI-SPEC-120 — Модел на научния обект
3. Терминология и определения

Моделът „Scholarly Object“ се намира тук, тъй като той дефинира общата абстракция, използвана от специализираните модели.

„Терминология и определения“ има едно стандартно място в страничната лента в тази категория. Документите за управление и спецификациите ТРЯБВА да съдържат препратка към нея, вместо да я регистрират повторно в страничната лента.

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

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

Съдържа:

1. OMI-SPEC-100 — Модел на документа
2. OMI-SPEC-110 — Модел „Anchor“
3. OMI-SPEC-130 — Модел за анотиране
4. OMI-SPEC-140 — Модел на метаданните

Редът отразява основната посока на зависимостта:

Scholarly Object Model
        ↓
Document Model
        ↓
Anchor Model
        ↓
Annotation Model

Metadata Model applies across these layers.

Запазените спецификации, като например „Модел на идентичността и съавторството“, „Модел на версиите и промените“, „Модел на превода“, „Модел на валидирането“ и „Модел на сътрудничеството и разрешенията“, НЕ ТРЯБВА да се появяват като активни документи, докато не бъдат създадени техните канонични файлове.

7. Научен работен процес и публикуване

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

Съдържа:

1. OMI-SPEC-200 — Модел за преглед
2. OMI-SPEC-210 — Модел за цитиране
3. OMI-SPEC-220 — Модел на библиографска записка
4. OMI-SPEC-221 — Архитектура на справочната библиотека и регистъра
5. OMI-SPEC-230 — Модел за публикуване

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

В рамките на подсистемата за цитиране:

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

8. Платформа и борса

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

Съдържа:

1. OMI-SPEC-300 — Архитектура на плъгините
2. OMI-SPEC-310 — Платформа API
3. OMI-SPEC-320 — Формат на файла
4. OMI-SPEC-330 — Архитектура на контейнерите

Тези документи ТРЯБВА да останат отделени от семантичните модели.

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

9. Управление

Категорията „Управление“ съдържа документи, които регулират разработването, поддържането, зрелостта, идентичността и публикуването на стандарта „OMI“.

Съдържа:

1. Устав
2. План за развитие на „OMI“ 1.0
3. Архитектурен одит
4. Архитектура на документацията
5. Животният цикъл на спецификацията
6. Политика за версиите
7. Ръководство за стил при изготвяне на спецификации
8. Регистър на спецификациите

Регистърът на спецификациите е авторитетен източник за идентификаторите на спецификациите и каноничните пътища.

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

10. Целеви страници по категории

Всяка категория от най-високо ниво ТРЯБВА да предоставя генерирана индексна страница.

Генерираните индексни страници ТРЯБВА да съдържат:

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

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

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

Настоящите слъг-и на категориите са:

Категория	Слаг
Въведение	/introduction
Основи	/foundations
Основни семантични спецификации	/core-semantic-specifications
Научен работен процес и публикуване	/scholarly-workflow-publishing
Платформа и борса	/platform-exchange
Управление	/governance

Тези заглавия ТРЯБВА да останат непроменени след публикуването.

11. Правила за елементите в страничната лента

11.1 Изрична регистрация

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

Необходима е изрична регистрация, тъй като хранилището съдържа:

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

11.2 Етикети

Заглавието в страничната лента МОЖЕ да бъде по-кратко от заглавието на страницата.

Например:

Page title: OMI Architecture Map
Sidebar label: Architecture Overview

Етикетът НЕ ТРЯБВА да променя идентичността или нормативния обхват на документа.

11.3 Поръчки

Редът на спецификациите ТРЯБВА да следва архитектурата на каноничните идентификатори и зависимостите, а не реда на имената на файловете.

Редът на представяне на управлението ТРЯБВА да следва работния процес на читателя по отношение на стандартите:

constitutional authority
→ roadmap and audit
→ documentation architecture
→ lifecycle
→ versioning
→ authoring rules
→ registry

11.4 Състояние на категорията

Категориите от най-високо ниво ТРЯБВА да могат да се скриват и първоначално да са разгънати, докато наборът от документация все още е сравнително малък.

Състоянието „сгънато“ по подразбиране МОЖЕ да бъде преразгледано, когато броят на документите нарасне значително.

12. Стари и отменени страници

Старата страница НЕ ТРЯБВА да се показва в основната странична лента, когато съществува каноничен наследник.

Страницата с архива на адрес:

docs/specifications/scholarly-object-model.md

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

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

Каноничният документ е OMI-SPEC-120 — Модел на научния обект.

Старите страници ТРЯБВА:

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

13. Пътища към файлове и концептуални категории

Категорията в страничната лента не е необходимо да съвпада напълно с името на изходната директория.

Например:

• docs/foundations/architecture-map.md се намира в раздела „Въведение“;
• docs/specifications/core/scholarly-object-model.md фигурира в раздела „Основи“;
• docs/governance/terminology.md се появява в раздела „Основи“.

Това е умишлено.

Рефакторирането на файловата система ТРЯБВА да се извършва само когато осигурява ясна полза за поддръжката и може безопасно да запази публичните маршрути.

14. Идентификатори на документи

Docusaurus Идентификаторите на документите ТРЯБВА да останат уникални.

Идентификаторът на документа ТРЯБВА да остане непроменен, след като документът стане обект на публично позоваване.

Когато в предната част е деклариран изричен идентификатор на документа от типа „id“, страничната лента ТРЯБВА да използва решената стойност на идентификатора „Docusaurus“, вместо да се основава само на името на файла.

При рефакторирането на страничната лента НЕ СЕ ДОПУСКА промяна на идентификаторите на спецификациите на OMI, като например OMI-SPEC-120. Идентификаторите на документи на Docusaurus и идентификаторите на спецификации на OMI представляват отделни пространства от имена.

15. Вътрешни връзки

Документите ТРЯБВА да използват относителни връзки от типа Markdown, когато се препращат към документи от същото хранилище.

Организацията на страничната лента НЕ ТРЯБВА да се разглежда като заместител на изричните препратки към нормативни документи.

Зависимостта от спецификацията ТРЯБВА да бъде посочена в самата спецификация, дори когато двата документа са разположени един до друг в страничната лента.

При прегледа на вътрешните връзки СЛЕДВА да се провери:

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

16. Локализация

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

Структурите на унгарската и немската документация ТРЯБВА да отразяват концептуалната йерархия на английската версия.

Етикетите на категориите в страничната лента и текстът от генерирания индекс ТРЯБВА да бъдат включени в обичайния работен процес по превод на Docusaurus.

Преводът ТРЯБВА да запази:

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

Преведената страница НЕ ТРЯБВА да получава отделен идентификатор по спецификацията „OMI“.

Когато даден документ на английски език претърпи промени, АКТУАЛНОСТТА на превода ТРЯБВА да се проследява в съответствие с Политиката за версии и документа „Терминология и дефиниции“.

17. Добавяне на нов документ

Преди да бъде добавен нов документ в страничната лента, неговият автор ТРЯБВА да определи:

1. дали документът е нормативен, информационен, свързан с конкретно изпълнение или с управлението;
2. дали вече има документ, който разглежда тази тема;
3. дали се изисква идентификатор на спецификацията;
4. дали идентификаторът е запазен или регистриран;
5. коя категория от най-високо ниво е канонична;
6. кои преки зависимости трябва да бъдат декларирани;
7. дали документът следва да бъде публично достъпен в настоящия етап от жизнения си цикъл;
8. дали са необходими преводи или заместващи символи за превод;
9. дали добавянето на документа променя вече генерираната страница с категории;
10. дали трябва да се запазят публичните маршрути или старите псевдоними.

Новата нормативна спецификация ТРЯБВА да бъде въведена в Регистъра на спецификациите, преди да бъде представена с постоянен идентификатор от типа „OMI-SPEC“.

18. Премахване или замяна на документ

Активен документ НЕ ТРЯБВА просто да изчезне от страничната лента и хранилището без решение за архивиране.

За подмяната са необходими:

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

19. Контролен списък за валидиране

Промяната в архитектурата на документацията е готова за преглед, когато:

• всеки идентификатор на документ от страничната лента се разрешава;
• всяка активна спецификация се появява точно веднъж;
• всеки документ, свързан с публичното управление, се появява точно веднъж, освен ако не е изключен умишлено;
• генерираните индексни слагове са уникални;
• старата страница „Scholarly Object Model“ не фигурира в списъка;
• каноничният модел на научния обект е посочен в раздела „Основи“;
• етикетите със спецификациите съответстват на Регистъра на спецификациите;
• описанията на категориите точно отразяват съдържанието им;
• нито един съществуващ изходен файл не се премества без план за запазване на пътя;
• влиянието върху локализацията е документирано;
• Docusaurus синтаксисът на конфигурацията е валиден;
• Създаването на документацията приключва без грешки, свързани с неработещи връзки или дублирани идентификатори.

20. Текущи резултати от миграцията

Първоначалното прехвърляне на страничната лента води до следната публична йерархия:

Introduction
├── Vision
└── Architecture Overview

Foundations
├── OMI-SPEC-000 — Core Principles
├── OMI-SPEC-120 — Scholarly Object Model
└── Terminology and Definitions

Core Semantic Specifications
├── OMI-SPEC-100 — Document Model
├── OMI-SPEC-110 — Anchor Model
├── OMI-SPEC-130 — Annotation Model
└── OMI-SPEC-140 — Metadata Model

Scholarly Workflow and Publishing
├── OMI-SPEC-200 — Review Model
├── OMI-SPEC-210 — Citation Model
├── OMI-SPEC-220 — Bibliographic Record Model
├── OMI-SPEC-221 — Reference Library and Registry Architecture
└── OMI-SPEC-230 — Publishing Model

Platform and Exchange
├── OMI-SPEC-300 — Plugin Architecture
├── OMI-SPEC-310 — Platform API
├── OMI-SPEC-320 — File Format
└── OMI-SPEC-330 — Container Architecture

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

21. Бъдещо разширение

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

Възможните бъдещи категории включват:

• Ръководства за внедряване;
• Профили и разширения;
• Схеми и примери;
• Съответствие и тестване;
• Общност и принос.

НЕ СЛЕДВА да се създава нова категория от най-високо ниво за един-единствен документ, освен ако тази категория не отразява трайно архитектурно разграничение.

Документацията, свързана с конкретната реализация, ТРЯБВА да остане ясно отделена от нормативните спецификации OMI.

22. Поддръжка

Архитектурата на документацията СЛЕДВА да бъде преразгледана, когато:

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

Промените в този документ и в „sidebars.js“ обикновено ТРЯБВА да се разглеждат заедно, когато се променя концептуалната йерархия.

23. Осиновяване

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

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

Приемането на тази архитектура не води до преминаването на нито един проект на спецификация в статуса „Кандидат за преглед“, „Кандидат за внедряване“ или „Стабилен“.

24. Обобщение

Пакетът с документация на „OMI“ е организиран като система от регулирани стандарти, а не като хронологична колекция от страници.

Архитектурата осигурява:

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

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