Оформление диздока с фокусами

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

При реализации фокусов могут возникнуть препятствия, возникающие из-за неполноты или противоречивости описания. В результате этого возникает необходимость задавать дополнительные вопросы автору диздока и ждать ответа. Чем загруженнее автор, тем дольше ожидание. В результате теряется много времени.

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

1. Формальность и простота. Чем проще и понятнее описан диздок, тем быстрее он воспринимается кодером и, соответственно, реализуется.

2. Строгость формата. Когда один диздок оформлен аналогично предыдущему, то кодер легко сможет перейти от одного диздока к другому.

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

Далее будет приведён пример небольшого псевдодиздока. Основные его составляющие: диаграмма и текстовый документ.

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

Диаграмма должна быть выполнена в форматах SVG и PNG (высокого разрешения). SVG-диаграмма требуется для того, чтобы можно было разглядеть все детали очень большого дерева. А PNG-диаграмму необходимо будет поместить в текстовый документ.

Используйте этот документ как шаблон для написания диздоков. Скопируйте его и меняйте его содержание, оставляя структуру.

Для рисования диаграмм рекомендуется использовать сервис draw.io. Шаблон диаграммы, приведённой выше, можно скачать по этой ссылке. В самом сервисе необходимо будет открыть данный файл и использовать его как шаблон. Вы также можете построить диаграмму самостоятельно. Придерживайтесь следующей нотации:

1. Сам фокус находится в прямоугольном блоке и содержит его название.

2. Стрелка от фокуса к фокусу означает отношение родительского фокуса к дочернему.

3. Двунаправленная стрелка между двумя фокусами с буквой "X" посередине означает, что эти два фокуса являются взаимоисключающими (букву разрешается опускать). На диаграмме фокусы B0 и C0 являются взаимоисключающими.

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

   • Фокусы B1, B2, C1 и C2 доступны, если завершен либо B0, либо С0. При этом легко видеть, что эти два фокуса взаимоисключающие.
   • Фокус B3 доступен, если выполнен хотя бы один из фокусов B1 и B2.

5. Сплошная линия от нескольких родительских фокусов означает, что дочерний будет доступен тогда, когда все родительские будут завершены. Пример: фокус C3 будет доступен только при завершении C1 и C2.