diff --git a/.yfm b/.yfm index 7c16ee3..f020e3d 100644 --- a/.yfm +++ b/.yfm @@ -1,4 +1,3 @@ -disableLiquid: true allowHTML: true langs: ['en','ru'] diff --git a/en/project/leading-page.md b/en/project/leading-page.md index 8f94f86..2405c49 100644 --- a/en/project/leading-page.md +++ b/en/project/leading-page.md @@ -51,12 +51,12 @@ Possible comparison operators: `==`, `!=`, `<`, `>`, `<=`, and `>=`. Title and description of document and links support [substitutions](../syntax/vars#subtitudes) and [conditional operators](../syntax/vars#conditions). ```yaml -title: "{{ title }}" -description: "{% if version == 10 %}{{ description_legacy }}{% else %}{{ description }}{% endif %}" +title: "not_var{{ title }}" +description: "{% if version == 10 %}not_var{{ description_legacy }}{% else %}not_var{{ description }}{% endif %}" meta: - title: "{{ meta_title }}" + title: "not_var{{ meta_title }}" links: -- title: "{{ link_title }}" - description: "{{ link_description }}" +- title: "not_var{{ link_title }}" + description: "not_var{{ link_description }}" href: path/to/conditional/file.md ``` diff --git a/en/project/toc.md b/en/project/toc.md index 0b8e7d4..c7d828f 100644 --- a/en/project/toc.md +++ b/en/project/toc.md @@ -50,7 +50,7 @@ Possible comparison operators: `==`, `!=`, `<`, `>`, `<=`, `>=`. Document title supports [substitutions](../syntax/vars#subtitudes) and [conditional operators](../syntax/vars#conditions). ```yaml -title: "{{ title }}" +title: "not_var{{ title }}" ``` {% note warning %} diff --git a/en/syntax/vars.md b/en/syntax/vars.md index f396a85..5af6658 100644 --- a/en/syntax/vars.md +++ b/en/syntax/vars.md @@ -12,13 +12,13 @@ Methods for using variables in documents are discussed below. To substitute a value with a variable in the text, enter the variable name with double curly brackets before and after. ``` -Some text {{ variable_name }} text continued. +Some text not_var{{ variable_name }} text continued. ``` If the text contains double curly brackets but doesn't require variable substitution, add `not_var` before the construction. ``` -Some text not_var{{ also_text }} text continued. +Some text not_varnot_var{{ also_text }} text continued. ``` ## Conditional operators {#conditions} @@ -50,7 +50,7 @@ Use loops to output repetitive content for each element of an array. Inside the ``` {% for variable_name in array_name %} -Some text {{ variable_name }} text continued. +Some text not_var{{ variable_name }} text continued. {% endfor %} ``` @@ -69,7 +69,7 @@ default: Then using loops will result in the following: ```markdown -Prefix {% for user in users %} {{user}} {% endfor %} Postfix +Prefix {% for user in users %} not_var{{user}} {% endfor %} Postfix ``` Prefix Alice Mark Postfix @@ -79,7 +79,7 @@ Prefix {% for user in users %} -{{user}} +not_var{{user}} {% endfor %} @@ -118,15 +118,15 @@ default: Then using filters will result in the following: ```markdown -Hello {{ user.name | capitalize }}! +Hello not_var{{ user.name | capitalize }}! ``` Hello Alice! ```markdown -{{ users | length }} +not_var{{ users | length }} -{{ user.name | length }} | length +not_var{{ user.name | length }} | length ``` 2 @@ -156,9 +156,9 @@ default: Then using functions will result in the following: ```markdown -Hello P{{ user.name.slice(1) }}! +Hello Pnot_var{{ user.name.slice(1) }}! -Hello P{{ user.name.slice(1, 2) }}vel! +Hello Pnot_var{{ user.name.slice(1, 2) }}vel! ``` Hello Pasha! diff --git a/ru/_images/camera.svg b/ru/_images/camera.svg new file mode 100644 index 0000000..2db335d --- /dev/null +++ b/ru/_images/camera.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/ru/_images/highload.png b/ru/_images/highload.png new file mode 100644 index 0000000..5bcffdc Binary files /dev/null and b/ru/_images/highload.png differ diff --git a/ru/_images/subbotnik.jpg b/ru/_images/subbotnik.jpg new file mode 100644 index 0000000..028ac65 Binary files /dev/null and b/ru/_images/subbotnik.jpg differ diff --git a/ru/presets.yaml b/ru/presets.yaml new file mode 100644 index 0000000..159be9b --- /dev/null +++ b/ru/presets.yaml @@ -0,0 +1,18 @@ +default: + algorithms: | + - Массив - и его отличие от списков + - Связный список - и его реализации на js + - Двусвязный список - и где его применяют + - Hash-map - почему эффективен + - Дерево, бинарное дерево, AST - красно-черные не нужны, мы про другое + + servers: | + - NodeJS - основная среда исполнения кода + - S3/S3 API - хранилище контента + - PostgreSQL - хранилище пользовательских данных + - OpenSearch/ElasticSearch - индекс по документациям + - Redis - кеширование серверных ответов + - Kubernetes/Kubernetes like - управление контейнерами + - Terraform + Helm - автоматическое разворачивание инсталяции, автоматический деплой + - ALB/API Gateway/Nginx - балансеры + - Serverless - внутренние задачи инсталяции \ No newline at end of file diff --git a/ru/project/leading-page.md b/ru/project/leading-page.md index d054fbe..d72d90e 100644 --- a/ru/project/leading-page.md +++ b/ru/project/leading-page.md @@ -52,12 +52,12 @@ links: Название и описание документа и ссылок поддерживают [подстановки](../syntax/vars#subtitudes) и [условные операторы](../syntax/vars#conditions). ```yaml -title: "{{ title }}" -description: "{% if version == 10 %}{{ description_legacy }}{% else %}{{ description }}{% endif %}" +title: "not_var{{ title }}" +description: "{% if version == 10 %}not_var{{ description_legacy }}{% else %}not_var{{ description }}{% endif %}" meta: - title: "{{ meta_title }}" + title: "not_var{{ meta_title }}" links: -- title: "{{ link_title }}" - description: "{{ link_description }}" +- title: "not_var{{ link_title }}" + description: "not_var{{ link_description }}" href: path/to/conditional/file.md ``` diff --git a/ru/project/toc.md b/ru/project/toc.md index 0441ba4..65aa104 100644 --- a/ru/project/toc.md +++ b/ru/project/toc.md @@ -50,7 +50,7 @@ items: Название документа поддерживает [подстановки](../syntax/vars#subtitudes) и [условные операторы](../syntax/vars#conditions). ```yaml -title: "{{ title }}" +title: "not_var{{ title }}" ``` {% note warning %} diff --git a/ru/syntax/vars.md b/ru/syntax/vars.md index 304e6da..1642186 100644 --- a/ru/syntax/vars.md +++ b/ru/syntax/vars.md @@ -63,7 +63,7 @@ default: ``` Тогда использование циклов приведет к следующим результатам: ```markdown -Prefix {% for user in users %} {{user}} {% endfor %} Postfix +Prefix {% for user in users %} not_var{{user}} {% endfor %} Postfix ``` Prefix Alice Mark Postfix @@ -72,7 +72,7 @@ Prefix {% for user in users %} -{{user}} +not_var{{user}} {% endfor %} @@ -110,15 +110,15 @@ default: Тогда использование фильтров приведет к следующим результатам: ```markdown -Hello {{ user.name | capitalize }}! +Hello not_var{{ user.name | capitalize }}! ``` Hello Alice! ```markdown -{{ users | length }} +not_var{{ users | length }} -{{ user.name | length }} | length +not_var{{ user.name | length }} | length ``` 2 @@ -147,9 +147,9 @@ default: Тогда использование функций приведет к следующим результатам: ```markdown -Hello P{{ user.name.slice(1) }}! +Hello Pnot_var{{ user.name.slice(1) }}! -Hello P{{ user.name.slice(1, 2) }}vel! +Hello Pnot_var{{ user.name.slice(1, 2) }}vel! ``` Hello Pasha! diff --git a/ru/toc.yaml b/ru/toc.yaml index 7f32ee5..82a692b 100644 --- a/ru/toc.yaml +++ b/ru/toc.yaml @@ -118,3 +118,8 @@ items: href: contribution.md - name: Релизы YFM href: changelog.md + - name: Вакансии + hidden: true + items: + - name: Старший разработчик + href: vacancy.md \ No newline at end of file diff --git a/ru/vacancy.md b/ru/vacancy.md new file mode 100644 index 0000000..d21b124 --- /dev/null +++ b/ru/vacancy.md @@ -0,0 +1,153 @@ +# Веб-разработчик в Платформу документации + + + +## Специфика нашей работы + +Мы занимаемся разработкой программной платформы документации в парадигме [documentation as a code](https://yandex.ru/search/?text=documentation+as+a+code&clid=1955453&win=547&lr=2). + +Платформа помогает разработчикам и техническим писателям получать качественную документацию, прилагая минимум усилий. + +На нешей платформе создана вся документация [Облака](https://cloud.yandex.ru/ru/docs), [Diplodoc](https://diplodoc.com/docs/ru/), страница, которую вы сейчас читаете, и много других продуктов, которые вы пока не сможете увидеть. + +Концепция documentation as a code предполагает, что написание документов следует **[принципам написания кода](*documentation-as-a-code-rules)**, целью которых является создание четкой структуры для легкого понимания и чтения. + +### Минимум верстки + +В плане интерфейса документация - простой сервис. + +Основные интерфейсные компоненты мы берем из open source библиотеки [@gravity-ui/uikit](https://gravity-ui.com/libraries/uikit). + +Для сложного пользовательского контента мы предоставляем интеграцию с [@gravity-ui/page-constructor](https://gravity-ui.com/libraries/page-constructor). + +### Максимум логики + +Большая часть нашей работы связана с процессингом текстов, расширением синтаксических [конструкций маркдауна](https://github.com/diplodoc-platform/transform/blob/master/src/transform/plugins/table/index.ts), созданием новых [расширений](https://github.com/diplodoc-platform/mermaid-extension) для платформы. + +Важно не теряться в инкрементах циклов, не создавать излишней вложенности. умело выбирать **[структуры данных](*data-structures)**. + +### Сервера{#servers} + +Платформа работает не только как набор утилит для сборки документации, +но и в виде нескольких серверных инсталяций, которые помогают динамически рендерить документацию, индексировать ее. + +Основные технологии с которыми мы работаем на серверах: +{{servers}} + +Со всеми перечисленными технологиями мы работаем лично. Следим за стабильностью серверов. Прорабатываем архитектуру. Выстраиваем процессы для обеспечения стабильности. + +{% note info %} + +Суммарно на наши сервера заходит больше одного миллиона уникальных пользователей в день. + +{% endnote %} + +{% note warning %} + +Наша задача быстро и без ошибок, в любую погоду, показывать документацию пользователям. + +{% endnote %} + +### OpenSource + +Большая часть нашей платформы [размещена в open source](https://github.com/diplodoc-platform/diplodoc). + +Поддержка open source является важной частью нашей ежедневной работы: + +- Общение в issues и pull requests в GitHub на русском и преимущественно английском языке. +- Презентация/продвижение продукта на разных **![i](./_images/camera.svg) [конференциях](*conference)**{.photo} и **![i](./_images/camera.svg) [митапах](*meetup)**{.photo}. +- Разработка продукта не под конкретную компанию, а под совокупный опыт/ожидания сообщества. + +## Ожидания от кандидата + +Мы ожидаем что вы уже знаете или вам было бы **интересно** быcтро изучить: + +{% cut "Алгоритмы и структуры данных" %} + +Ничего экзотического не требуется. Но в базовых нужно разбираться хорошо. Умело их применять. + +{{algorithms}} + +Отдельным плюсом будет, если вы сталкивались с алгоритмами токенизации текстов, разбираетесь в алгоритмах поиска по текстам. + +Потому что мы разбираем тексты на кусочки, а потом собираем из них что-нибудь новое и прекрасное. + +{% endcut %} + +{% cut "Серверные архитектуры" %} + +{{servers}} + +Потому что [мы много работаем с серверами](#servers) + +{% endcut %} + +{% cut "Форматы" %} + +**CommonMark** спецификаци маркдауна. + +**GitHub Flavored Markdown** спецификаци маркдауна. + +**JSONSchema** - работаем со схемами чаще среднестатистического разработчика + +{% endcut %} + +{% cut "Open Source технологии" %} + +**Git** - чуть глубже чем просто создание коммитов. Мы используем его на программном уровне. + +**GitHub** - так же глубоко интегрирован в наш продукт. Пишем gh-actions, gh-extensions дл внешних потребителей платформы документации. + +**Webpack** - на уровне написани собственных плагинов. + +{% endcut %} + +{% cut "Литература" %} + +Мы будем лучше друг друга понимать, если вы уже читали: + +**Чистый код** Роберта Мартина + +**Чистая архитектура** Роберта Мартина + +**Site Reliability Engineering** Бетси Бейер и др. + +{% endcut %} + +Так же мы ожидаем хороший скилл коммуникации. У нас много внешних и внутренних заказчиков. +Много демократичных процессов в рамках развития общей опенсорс технологии. +Нужно много слушать, анализировать, договариваться. + + +[*documentation-as-a-code-rules]: +- **DRY (Don’t Repeat Yourself)**: важно избегать дублирования информации в документах. +- **KISS (Keep It Simple, Stupid)**: необходимо избегать ненужной сложности и стремиться к простоте изложения информации. +- **SRP (Single Responsibility Principle)**: каждый блок документации должен быть ответственным только за одну часть функциональности для сохранения четкости. структуры. +- **SLAP (Single Level of Abstraction Principle)**: необходимо разбивать большие документы на уровни абстракции и делать для каждого уровня отдельные лаконичные документы. +- **LoD (Law of Demeter)**: необходимо делать ссылки только на релевантные документы. +- Система ориентирована на пользователя, в ней ценятся не только читаемость, но и визуальная составляющая. Поэтому использование визуальных средств, таких как диаграммы, графики и видеоруководства, также становятся все более важными. +- **Проверка качества**: система предполагает единый стиль кодирования, включая структуру текста, отступы, пробелы и т.д. для облегчения понимания. +- **Версионирование**: система интегрирована с популярными vcs. +- **Локализация**: система доступна пользователям на нескольких языках. Это обеспечивается интеграцией с [автоматическими](https://cloud.yandex.ru/ru/docs/translate/?from=int-console-empty-state) и [полу-автоматическими](https://ru.smartcat.com/) сервисами перевода. +- **Доступность**: система доступна плохо видящим пользователям. + +[*data-structures]: +{{algorithms}} + +[*meetup]: +![i](./_images/subbotnik.jpg) + +[*conference]: +![i](./_images/highload.png)