мы будем использовать markdown. сам по себе это облегчённый язык разметки, созданный с целью обозначения форматирования в простом тексте, с максимальным сохранением его читаемости человеком, и пригодный для машинного преобразования в языки для продвинутых публикаций
по своей сути идея markdown так же используется и в целях унификации. написанное на markdown проще распространять на сторонние ресурсы, мало того, достаточно просто написать парсер, который в свою очередь позволит интегрировать эту документацию куда угодно
мы используем идею блоков, что бы всегда в определённой комбинации форматированного текста читатели могли видеть патерн того, что конкретно вы пытаетесь им преподнести. помимо этого в документации должно быть минимальное количество разновидности этих блоков, с очень определённой причиной их использования (что потребуется и для максимальной совместимости)
документация сделана так, что бы работать в obsidian, github, discord и deep-case(на данный момент проводятся тесты) одновременно для удобства написания. работать мы будем с *.md файлами, которые расшифровываются как markdown файлы
по своей сути просто удобный текстовый редактор с возможностью написания markdown заметок. в нашем случае такие заметки называются страницами и наша документация пишется как раз по стандарту markdown, посему мы используем obsidian для её написания. вы можете использовать любой редактор текста с поддержкой markdown, только убедитесь что все определённые нами блоки совместимы с вашим редактором, откройте этот *.md файл с помощью редактора
блоки это некоторая логическая единица текста которая может восприниматься целостно в зависимости от контекста. так, вы к примеру можете сказать "прочти темы касательно связей в элементах deep". грамотная структура имеет не последнее значение в изучении. мало просто выложить информацию, нужно дать максимально лаконичную информацию, логично связанную между собой
ниже перечислены разновидности блоков, от самого большого к самому маленькому
является элементом документации, представлен в текстовых *.md файлах содержащий в себе текст. первая и главная страница это README.md далее страницы могут быть названы произвольно на ваше усмотрение (желательно маленькими буквами), но для удобства ведения структуры, названия файлов должны жестко ссылаться на тему внутри них, а так же если вам нужно что то перечислить то пишите это через '-' (например 'deep-case-my_package')
является элементом страницы, то что находится в начале страницы, как правило они одноименны файлу (что бы структура была нагляднее). нужны для обозначения глобальной темы работающей в своём контексте. начинаются с '#' (с пробелом) и заканчиваются на '---'
- их так же может быть несколько на странице, идут они строго после друг друга и в будущем могут быть разделены на независимые страницы, так что и писаться текст в заголовке должен независимо
выносят из темы конкретные понятия или направления о которых будет вестись речь в этих блоках. начинаются с '####' (с пробелом) и заканчиваются двумя отступами (что бы визуально было отличимо от блоков абзацев)
- стоит так же добавить что могут быть нулевые подзаголовки сразу после заголовка или между другими подзаголовками (без имени подзаголовков). они относятся к общей теме и помогают в введении, повествования и переходе между понятиями. на них нельзя ссылаться
обычный текст. мной было принято что большими буквами текст в абзацах писаться не будет, что бы не цеплять глаз обилием синтаксических элементов. так же, конец абзацев не заканчивается на точку, для красоты. я предполагаю этот момент чистая вкусовщина и только косвенно повлияет на написание, в целом вы можете применять стандартные правила орфографии если вы хотите, это не должно на что то повлиять. начинается с любой буквы с красной строки и заканчивается одиночным отступом
является краеугольным инструментом создания ветвей документации или расширения её дополнительной информацией из интернета. ссылки немного отличаются по принципам синтаксиса, но в общем виде текст для ссылки обременяется в '[]' а сама ссылка помещается в '()' сразу после
- расположение может переходить и в родительские директории, стоит использовать '..' что бы спустится на уровень ниже
виды ссылок:
- на другой сайт, просто обременяется в '()'
- на другую страницу, пишите расположение относительно папки в которой находится этот *.md файл
- на заголовок или подзаголовок, все то же что и со ссылкой на страницу но дополнительно добавьте '#' или '####' и название (слитно)
перечисления чего бы то не было, в уместных случаях и не очень. удобный вид для множества выражений имеющих отношение к одному понятию или направлению используются как абзацы но главное выражение заканчивается на ':' а перечисление всегда идет с красной строки и начинается на '-'
что бы написать какой то блок кода, то для начала напишите выражение и после ':', а после с красной строки обремените ваш код в '```' только делайте все с красной строки, после первых '```' напишите какой синтаксис
как правило это статическое или динамическое изображение, показывающее пример в статике или динамике, что бы для человека это было нагляднее. что бы вставка работала, изображение должно открыто хранится по ссылке или же находится локально в документации. что бы вставить изображение напишите "![" после имя которое вы хотите дать вставке, после "](" и ссылку на ваше изображение, закройте конструкцию ")"
- обратите внимание что локальная ссылка считается локально от вашего *.md файла, для перехода в корень используйте ".." внутри ссылки
по своей сути какая та определённая односложная мысль изложенная в предложении. используются где бы то не было и иногда могут быть использованы для задания слов или их модификации. могут быть использованы в перечислении и тд.
что бы люди различали какие слова (иногда и выражения) написаны для объяснения, а какие отсылают к конкретно обозначенным во время обучения вещам, такие слова должны помечаться курсивом, что бы люди подсознательно понимали в локальном ли контексте это сказано. обремените ваше выражение ** и слово станет курсивным
(нужны для того, что бы можно было вводить локальные понятия и проводить их сквозь темы вырабатывая у человека общую с другими формулировку для упрощения общения пользователей deep в будущем)
то что требуется для дополнения контекста, но не имеющее отношение к этой конкретной теме. используйте это, что бы ссылаться на другие темы, понятия или вообще примеры из друг сфер деятельности. обременяются в '()'
такая информация пишется как нулевые подзаголовки, с тем лишь отличием что пишется она большими буквами (для привлечения внимания) и с красной строки должен располагаться символ '*'. данных блоков не должно быть в релизной версии
- аналогичным образом работает временная информация в тексте, пишется она между "~~" но в данном случае используется как инструмент. что бы показать что тут что то будет или что бы указать на что то, что было ранее
тот текст, который должен быть скрыт до будущего времени (к примеру страница к которому отсылается текст, не готова). делается при помощи html тега 'nobr' и атрибута hidden. в начале '<nobr tittle="' содержимое которое хотите скрыть и '">..</nobr>' в конце
- '..' нужны что бы не потерять то что вы оставили
как правило пишется только в тех страницах, к которым нет доступа с главной страницы. означает что какой то блок требует доработки или написания. что бы отметить блок для доработки, в любом его месте оставьте '???'
чеклист то же что и список, отличающийся возможностью указать на исполнение или не исполнение понятия, несовместим с discord. как правило это тоже временный блок, так что стоит стараться избегать таких блоков в релизной версии. делается так же как и список, только вместо '-' нужно указать '- [ ]' для незавершённого и '- [x]' для завершённого понятия
нужны для удобного поиска блоков по категориям. несовместимы с discord, однако все ещё способны выполнять свою функцию в частично виде. не стоит злоупотреблять этим инструментом и использовать в страницах перечесления. пишутся перед заголовков или подзаголовков, вначале пишете '#' а после сразу же название тега, следующий блок пишется с красной строки
как и теги, пишутся перед заголовками и подзаголовками, работают как ссылки, позволяют указать источник блока
использовать можно только выше перечисленные блоки, все что не входит в этот перечень может плохо повлиять на читаемость или совместимость с документацией на разных источниках. если хотите добавить какой либо новый блок, пожалуйста обратитесь ко мне (tand) (discord, vk)