> For the complete documentation index, see [llms.txt](https://mp4.gitbook.io/standard/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mp4.gitbook.io/standard/knowledge/bim/process/writing-rules.md).

# Правила ведения стандарта и базы знаний

{% hint style="success" %}
В качестве информационной среды для размещения выбран сервис **GitBook**.&#x20;
{% endhint %}

## Общие принципы

1. **Избегайте дублирования.** Информационные пространства не должны допускать дублирования информации без прямой необходимости. Данный принцип имеет несколько прямых следствий:

* Информационные пространства имеют ссылочную модульную структуру. Каждый процесс описан в отдельной инструкции (модуле), а связь между описанием различных взаимозависимых процессов осуществляется с помощью ссылок.
* Информация делится на общую и разделоспецифичную (АР, КР, ИОС и т.д.). Информация упоминается в разделе лишь при своей уникальности для данного раздела, в случае применения к нескольким разделам информация помещается в общую.

{% hint style="info" %} <mark style="color:red;">Плохо:</mark> описывать процесс работы и настройки спецификации в каждой инструкции

<mark style="color:$success;">Хорошо:</mark> при необходимости описания работы спецификаций дать ссылку на статью по [спецификациям](/standard/knowledge/methodology/instruction/specifikacii.md)
{% endhint %}

2. **Пишите просто, но понятно.** При написании следует избегать сложных формулировок и малоизвестных или технических терминов (или давать расшифровку с помощью аннотаций). Также следует сокращать алгоритмы действий до коротких формулировок.

{% hint style="info" %} <mark style="color:red;">Плохо:</mark> Для генерации нового вида необходимо перейти на вкладку **Вид**, затем найти панель **Создание**, после чего нажать на кнопку **План этажа...**

<mark style="color:$success;">Хорошо:</mark> Для cоздания новый вид воспользуйтесь инструментом "План этажа" (вкладка "Вид")...
{% endhint %}

3. **Не усложняйте разметку статей.** В подавляющем большинстве случаев для написания статьи необходимы только заголовки (Heading), текстовые блоки (Paragraph), списки (List), таблицы (Table) и рисунки (Drawing). Чем проще выполнена разметка статьи, тем проще ее читать и редактировать.
4. **Используйте скриншоты и GIF**. Применение скриншотов и GIF позволяет существенно сократить размер статьи без потери ее смыслового содержания.
5. **Используйте плашки (Hint)**. Плашки позволяют выделить важную информацию из монотонного массива текста и визуально "разбавляют" статью.
6. **Уведомляйте коллег.** При написании новых или редактировании существующих инструкций между ресурсами и информационными пространствами формируется взаимовлияние.
7. **Скрывайте неактуальные или находящиеся в работе статьи**. Пустые или находящиеся в работе инструкции необходимо скрывать из публикуемой версии и исключать из поисковых запросов с помощью механизма архивации и скрыти&#x44F;**,** описанного ниже.

## Информационные пространства

<img src="https://2028123183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq0Ee0SvSzmZfXRXepEDT%2Fuploads%2FdMMKCgcl5Cq96hiWsAa2%2Ffile.excalidraw.svg?alt=media&amp;token=1fb6460f-dbf9-41af-bd78-9c8404011f3d" alt="" class="gitbook-drawing">

### BIM-стандарт

1. BIM-стандарт представляет из себя совокупность **требований**, предъявляемых к информационному моделированию в рамках компании, и не описывает подробности применения инструментов и методики проектирования для выполнения этих требований.&#x20;
2. BIM-стандарт обладает полностью нумерованной структурой (цифры для основной части, буквы для приложений), т.к. в некоторых случаях необходимо точечное указание требований или текстовые ссылки на конкретные пункты.
3. BIM-стандарт **не ссылается** на Базу знаний, т.к. может быть использован для передачи заказчику.

### База знаний

1. База знаний представляет из себя совокупность **инструкций, регламентов,** которые применяются при реализации конкретных задач и подробно описывают применение инструментов и методики проектирования.
2. База знаний имеет нумерованную структуру лишь на верхнем уровне.
3. База знаний предполагает разделение информации по назначению: инструкции для проектировщиков не должны содержать информацию для BIM-специалистов, и наоборот.
4. База знаний в случае предметных требований **должна ссылаться** на BIM-стандарт.
5. База знаний должна описывать любой из процессов 2-мя способами - с учетом и без учета текущей автоматизации (на случай сбоев или неприменимости автоматизации в текущем проекте).

### Опубликованные сайты

В зависимости от назначения информационных пространств существует 2 сайта:

1. Сайт с **BIM-стандартом** для передачи внешним исполнителям или заказчикам **-** [**https://mp4.gitbook.io/externalstandard**](https://mp4.gitbook.io/externalstandard)
2. Сайт с **BIM-стандартом** и **Базой знаний** для внутреннего корпоративного пользования **-** [**https://mp4.gitbook.io/standard**](https://mp4.gitbook.io/standard)

## Инструменты и правила оформления

### Структура документа

Верхний уровень Gitbook представляет из-себя сайты (**sites**) и пространства (**spaces**). Сайты могут содержать несколько пространств и представляют из себя контейнер и совокупность настроек для внешнего представления пространств. Одни и те же пространства могут содержаться внутри нескольких сайтов и представляют из себя ссылку (правка пространства приводит к изменениям во всех содержащих его сайтах).

Структура пространства содержит внутри себя группы и входящие в них страницы. Группы страниц содержат минимум 1 страницу и в случае данного пространства представлены 3-мя областями:

1. **Методология и инструкции** - содержат методики и инструкции информационного моделирования для проектировщиков;
2. **Плагины и скрипты** - содержат информацию о автоматизации информационного моделирования для проектировщиков;
3. **BIM-отдел** - содержат методики и инструкции BIM отдела.

Для добавления новой страницы необходимо поместить курсор между необходимыми инструкциями в структуре документа слева и дождаться появления необходимой кнопки:

<figure><img src="https://2028123183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq0Ee0SvSzmZfXRXepEDT%2Fuploads%2FH6e59CNhSsJXXCpoo7KL%2Fimage.png?alt=media&amp;token=a57cb080-da30-4540-b2ea-10c4847aab89" alt=""><figcaption></figcaption></figure>

При необходимости инструкции можно перемещать относительно друг друга и менять вложенность с помощью перетягивания в нужное место.&#x20;

Gitbook позволяет одновременно редактировать только инструкции одного пространства. Для этого необходимо выбрать любую инструкцию необходимого пространства и нажать соответствующую кнопку ![](https://2028123183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq0Ee0SvSzmZfXRXepEDT%2Fuploads%2FuXF6sZxdcWtQ5tW739Sw%2Fimage.png?alt=media\&token=82ab6574-4670-4f71-8e18-756129fe8b61).&#x20;

{% hint style="warning" %}
Перед существенным редактированием или удалением существующих инструкций необходимо выполнить их архивацию по обозначенному ниже механизму.
{% endhint %}

### Основные инструменты

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

{% hint style="warning" %}
Из-за особенностей редактирования с помощью визуального представления языка markdown, при редактировании недоступна команда отмены с помощью Ctrl + Z!
{% endhint %}

Инструкции на GitBook формируются с помощью добавления в тело инструкции **блоков** с помощью соответствующей кнопки:

<figure><img src="https://2028123183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq0Ee0SvSzmZfXRXepEDT%2Fuploads%2FSHzp3FDFDtKPfUdo5YrK%2Fimage.png?alt=media&amp;token=02e59e14-3076-4711-837a-d3b6f8fe9801" alt=""><figcaption></figcaption></figure>

Блоки возможно перемещать и менять местами с помощью удерживания и перетаскивания расположенной рядом с блоком кнопки ![](https://2028123183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq0Ee0SvSzmZfXRXepEDT%2Fuploads%2FSTku6etRo5Kh0fR2KFte%2Fimage.png?alt=media\&token=da15c7c9-ad41-412f-b4e6-8c9ef09dbd37). Также нажатие на данную кнопку позволяет открыть возможные настройки данного блока.

Основным блоком информации является текстовый блок-параграф (**Paragraph**), который формируется автоматически при создании новой строки с помощью кнопки "Enter".

Текстовые блоки поддерживают создание символов с помощью кодов, например, создание символа короткого тире "–" возможно с помощью комбинации "Alt + 0150".

Формирование структуры документа и области навигации слева происходит с помощью введения в тело инструкции блоков-заголовков (**Heading**). Существует 3 разновидности заголовков:

<figure><img src="https://2028123183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq0Ee0SvSzmZfXRXepEDT%2Fuploads%2FnykxDV0TE0HFSZDSbgyc%2Fimage.png?alt=media&amp;token=e982dcde-b817-41ad-9844-1a64e9b4af4a" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Рекомендуется не применять без прямой необходимости заголовки 3 уровня, т.к. они не отображаются в области навигации статьи справа и не сильно выделяются по сравнению с жирным выделенным текстом.
{% endhint %}

Для выделения важной текстовой информации и "разбавления" сплошных текстов следует применять плашки (**Hint**). При нажатии на значков информации плашка приобретает один из 4 возможных цветов, которые рекомендуется использовать в следующем контексте:

{% hint style="info" %}
Нейтральное содержание
{% endhint %}

{% hint style="warning" %}
Предупреждающее содержание
{% endhint %}

{% hint style="danger" %}
Крайне важное содержание
{% endhint %}

{% hint style="success" %}
Положительное содержание
{% endhint %}

Нумерованный список формируется с помощью соответствующих блоков-списков (list):

<figure><img src="https://2028123183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq0Ee0SvSzmZfXRXepEDT%2Fuploads%2FByPE1hf3Zfz0SujhpCnP%2Fimage.png?alt=media&amp;token=2ec18b9f-3f1e-4bed-b361-35bd41795717" alt=""><figcaption></figcaption></figure>

Для того, чтобы сформировать в пункте списка вложенный список необходимо нажать кнопку **Tab**:

* Список
  * Вложенный список

При введении в текст инструкции аббревиатур, требующих расшифровки, или терминов, требующих уточнения, рекомендуется пользоваться инструментов аннотации. Для этого необходимо выбрать необходимое слово и воспользоваться кнопкой аннотации![](https://2028123183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq0Ee0SvSzmZfXRXepEDT%2Fuploads%2FCLNdvD54P4IETOZUgOQE%2Fimage.png?alt=media\&token=805e5ac6-97fd-47ab-a077-6d3eb1701709). В данном случае выбранное слово получит нижнее [подчеркивание пунктирной линией](#user-content-fn-1)[^1] и будет отображать описание при нажатии на него.

Вставка скриншотов осуществляется с помощью классического копирования и вставки. Картинки или **GIF** могут быть расположены внутри текста или в виде отдельного блока.

Для формирования скриншотов рекомендуется использовать приложение ShareX. Элементы на скриншотах следует формировать в похожем стиле:

<figure><img src="https://2028123183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq0Ee0SvSzmZfXRXepEDT%2Fuploads%2Fy9h76dqrlEL9l32QufXU%2Fimage.png?alt=media&amp;token=6427b3e5-4eef-42f5-8133-85ba11592561" alt=""><figcaption></figcaption></figure>

Таблицы формируются с помощью блока-таблицы (**Table**) и имеют следующий вид:

<table><thead><tr><th width="201" data-type="number">Числовой столбец</th><th width="344" align="center">Столбец текстовый по центру</th><th data-type="checkbox">Столбец чек-боксов</th></tr></thead><tbody><tr><td>1</td><td align="center">текст</td><td>true</td></tr><tr><td>2</td><td align="center">Текст текст</td><td>true</td></tr></tbody></table>

Настройки таблицы можно разделить на 2 группы: общие настройки таблицы (видимость и размер столбцов, заголовков и т.д.) и настройки заголовков (тип данных, видимость размер). С помощью соответствующих ручек можно менять размер столбцов а также перетаскивать и менять местами столбцы или строки.

{% hint style="info" %}
Существует возможность размещать таблицы в качестве связи из сторонних сервисов, например, google sheets, однако максимально предпочтительный способом является формирование таблицы с помощью внутренних инструментов GitBook, т.к. это обеспечивает доступ для редактирования любым специалистом BIM-отдела.
{% endhint %}

Блок - рисунок (**Drawing**) позволяет формировать картинки, схемы, блок-схемы:

<img src="https://2028123183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq0Ee0SvSzmZfXRXepEDT%2Fuploads%2FtHofrvZhA9iTqtBe8W6Q%2Ffile.excalidraw.svg?alt=media&amp;token=76e95342-9fa8-49a8-99da-80e14b2f6683" alt="" class="gitbook-drawing">

{% hint style="info" %}
Аналогично таблицам способ формирования  **простых** картинок, схем, блок-схем предпочтительнее выполнять с помощью внутреннего инструмента GitBook, т.к. такой формат доступен для редактирования любым специалистом BIM-отдела.
{% endhint %}

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

{% hint style="success" %}
Чем проще выполнена разметка инструкции, тем проще ее читать и редактировать.
{% endhint %}

### Нежелательные инструменты

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

Не рекомендуется применять блок-вкладки (**Tabs**) по причине трудностей экспорта и печати такой информации:

{% tabs %}
{% tab title="Вкладка 1" %}
Часть информации...
{% endtab %}

{% tab title="Вкладка 2" %}
...не отобразится
{% endtab %}
{% endtabs %}

Не рекомендуется применять раскрывающиеся блоки информации (Expandable) по причине трудностей экспорта и печати такой информации:

<details>

<summary>Часть информации...</summary>

...не отобразится

</details>

Не рекомендуется внедрять в страницы файлы, особенно исполняемые, по причине возможного нарушения процесса синхронизации информации GitSync (см. ниже):

{% file src="/files/pc7PsfJqeb05OdBnTRnM" %}

### Настройки страницы

Общие настройки страницы расположены у заголовка страницы и отображаются при наведении на заголовок страницы в режиме редактирования:

<figure><img src="https://2028123183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq0Ee0SvSzmZfXRXepEDT%2Fuploads%2F6WIw95vha6WqMA8nIowV%2Fimage.png?alt=media&amp;token=88548852-6230-467b-80a0-177120e8ba07" alt=""><figcaption></figcaption></figure>

### Текст и его оформление

В процессе оформления сформированной инструкции следует соблюдать нижеописанные правила.

В целях поддержания единообразия шрифта и размера текста рекомендуется не использовать инструмент кодового блока (Code Block) без необходимости публикации кода:

<pre><code><strong>Хочу и пишу тут
</strong><strong>обычный текст без публикации кода.
</strong></code></pre>

При необходимости выделения в содержании текста конкретных сущностей (инструментов Revit, имен параметров, их значений, имен плагинов, проектов, компаний, файлов) необходимо применять кавычки ("") ,а не курсив, жирность, цвет или инструмент Keyboard ![](https://2028123183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq0Ee0SvSzmZfXRXepEDT%2Fuploads%2FJM5VYswzdLsBhKf4UWbd%2Fimage.png?alt=media\&token=035f4e81-2ebc-4efb-912b-02727ea07913).&#x20;

{% hint style="info" %} <mark style="color:red;">Плохо:</mark> инструментом *Стена*... параметру **ОП\_Тип помещения**... значение <mark style="color:green;">123</mark> ... компании <kbd>Моспроект 4</kbd> ... файл <mark style="color:blue;">**RSN.ini**</mark>...

<mark style="color:green;">Хорошо:</mark> инструментом "Стена"... параметру "ОП\_Тип помещения".. значение "123" ... компании "Моспроект &#x34;*"* ...файл "RSN.ini"...
{% endhint %}

При необходимости выделения некоторых слов или фраз в составе обычного текста рекомендуется выделять их жирным шрифтом.

{% hint style="info" %} <mark style="color:red;">Плохо:</mark> ... поэтому <mark style="color:red;">не рекомендуется</mark> удалять... перед выполнением *необходимо убедиться*... <kbd>следует</kbd>...

<mark style="color:green;">Хорошо:</mark> ... поэтому **не рекомендуется** удалять...перед выполнением **необходимо убедиться**... **следует**...
{% endhint %}

Рекомендуется использовать минимальное количество цветов текста в инструкциях и использовать выделение текста цветом только при обозначении составных частей сокращений, кодов, полей.

Расположенные в тексте пути к папкам следует выделять жирным шрифтом, например, **M:\Выделяй\ путь\жирным\И не ставь в конце точку, чтобы было удобно копировать и вставлять в проводник!**

Также следует учитывать правила применения следующих знаков:

<table><thead><tr><th width="161">Знак</th><th width="167">Комбинация</th><th>Употребление</th></tr></thead><tbody><tr><td>Дефис "-"</td><td>с клавиатуры</td><td><p>Дефис - орфографический знак, используется только внутри слов и <strong>никогда не отбивается пробелами</strong>:  </p><ul><li>20-процентный;</li><li>кое-что, где-нибудь;</li><li>веб-сайт, генерал-майор</li></ul></td></tr><tr><td>Короткое тире "–"</td><td>зажатый Alt + 0150</td><td><p>Короткое тире используется только для обозначения числовых интервалов, записанных цифрами, и <strong>никогда не отбивается пробелами</strong>: </p><ul><li>10–15 минут;</li><li>1941–1945 гг;</li><li>21:20–21:50</li></ul></td></tr><tr><td>Длинное тире "—"</td><td>зажатый Alt + 0151</td><td><p>Тире - пунктуационный знак, используется внутри предложений и <strong>всегда отбивается пробелами</strong>: </p><ul><li>век живи — век учись;</li><li>дорога в дождь — она не сладость</li></ul></td></tr><tr><td>Минус "-"</td><td>с клавиатуры</td><td><p>Используется в математических операциях и обозначениях отрицательного числа: </p><ul><li>3 = 2 - 1 (<strong>отбивается пробелами</strong>);</li><li>-3 (<strong>отбивается пробелом только от предыдущего символа</strong>)</li></ul></td></tr></tbody></table>

### Сохранение и синхронизация

Сохранение внесенных в инструкции пространства изменений происходит с помощью кнопки ![](https://2028123183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq0Ee0SvSzmZfXRXepEDT%2Fuploads%2Fw8bfvAXcN1Ex2YRjVzAU%2Fimage.png?alt=media\&token=9fea01d4-92af-4c2b-9283-ba982fd564e7).

{% hint style="info" %}
В случае совместной работы и внесения изменений возможны ситуации, когда придется предварительно принять изменения коллег с помощью нажатия кнопки **update**.
{% endhint %}

Работая с системой сохранения Gitbook, cледует помнить и учитывать в работе следующие моменты:

1. Изменения на опубликованных сайтах могут происходить **с задержкой**. Для того, чтобы убедиться, что изменения внесены, можно повторно зайти в режим редактирования или дождаться изменения в опубликованном пространстве (необходимо обновить страницу).
2. Переход в другое пространство, закрытие вкладки гитбука, возврат на предыдущую страницу (выход из режима редактирования) **могут привести к потере внесенных изменений**, а потому необходимо работать осторожно и с регулярностью производить сохранения.

{% hint style="success" %}
Для сохранности наработанной информации, при нажатии на кнопку сохранения Merge система синхронизации **GitSync** выполняет резервное сохранение редактируемого пространства в корпоративный **GitHub** (в формате markdown). Скачанные резервные копии хранятся по следующему пути: **M:\BIM\07\_Стандарт\00\_Archive\Резервные копии GitHub**&#x20;
{% endhint %}

### Архивация и скрытие страниц

Система архивации предназначена для минимизации риска потери информации. Архив базы знаний содержит устаревшие, но по любой причине необходимые, инструкции и **доступен только в режиме редактирования** пространства:

<figure><img src="https://2028123183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq0Ee0SvSzmZfXRXepEDT%2Fuploads%2FYLe9AckvPbwIYIdCkJ4i%2Fimage.png?alt=media&amp;token=785e6af9-61b1-46d0-88c5-019db80b3b95" alt=""><figcaption></figcaption></figure>

Для скрытия архивированных страниц в публичном пространстве и исключения их из поиска необходимо воспользоваться настройками страницы в режиме редактирования и привести их к следующему виду, т.е. **включить скрытие** и **отключить поисковое индексирование:**

<figure><img src="https://2028123183-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq0Ee0SvSzmZfXRXepEDT%2Fuploads%2F7gVag5j4FJXAofTtuJO8%2Fimage.png?alt=media&amp;token=a0c3b664-0cad-476b-91f8-d58cc6c8d3d4" alt=""><figcaption></figcaption></figure>

Вложенные страницы наследуют настройки видимости и скрытия их верхнеуровневых страниц.

{% hint style="warning" %}
Аналогичным образом можно поступать с находящимися в работе инструкциями.
{% endhint %}

[^1]: Привет)
