Доки что это такое
Запустилась Дока — опенсорсный справочник по веб-разработке
Дока — это опенсорсный справочник с документацией, который веб-разработчики пишут для веб-разработчиков. Цель Доки — сделать документацию по веб-разработке практичной, понятной и не скучной.
Это открытый проект, внести вклад в него может каждый. Контент и код Доки лежат на GitHub, правила участия, обсуждения и ревью проходят открыто для всех желающих.
Яндекс.Практикум поддерживает работу редакции Доки.
Как появилась идея Доки
Идея создать «добрую» документацию, в которой статьи будут написаны на понятном и несложном техническом языке, зародилась внутри Яндекс.Практикума в 2019 году. Тогда же появилась первая редакция и первые тексты. В конце 2020 года Дока стала активно развиваться, а 12 октября запустилась как независимый проект.
Осенью 2020-го ко мне пришёл Андрей Уродов из Практикума и предложил заняться проектом доброй документации для сообщества. Помню, меня тогда поразило слово «добрый», оно немного выпадало по смыслу, но когда я посмотрел на команду и подачу, я понял, о чём речь. Я всегда чувствовал эту болевую точку про источник знаний о веб-платформе и понимал, что это не просто безумная идея, а реальная потребность.
Я давно занимался «Веб-стандартами» — первым русскоязычным фронтенд-сообществом — и для меня это было понятным и интересным делом. Отдельно меня привлекла возможность поработать над опенсорсным проектом, в котором может принять участие любой желающий. Я подхватил эту идею и дожал её до полной открытости и публичности, чтобы проект не просто приносил пользу сообществу, но и развивался силами сообщества максимально прозрачно.
Вадим Макеев,
главный редактор Доки
Зачем нужна Дока
Главная задача Доки — предоставить веб-разработчикам понятные справочные материалы на русском языке, которые хорошо и нескучно написаны. Дока может быть полезна и тем, кто учится разработке, и тем, кто уже работает. Начинающим разработчикам она поможет разобраться в терминах, а уже прокачанным ребятам даст возможность делиться опытом и обмениваться знаниями.
Дока — для тех, кому нравится веб-разработка. Кто хочет учиться и вдохновляться, кто хочет делиться знаниями, делать разговор вокруг технологий визуально наглядным, захватывающим, привлекательным.
Задача Доки — в том, чтобы помочь новичкам не разочароваться в себе и предмете. В том, чтобы разработчики с опытом знали место, где можно найти ответы на профессиональные вопросы. И в том, чтобы культура обмена опытом, диалога о программировании двигалась в сторону продуктивной простоты и соответствовала тому запросу, который давно на виду.
Сергей Нугаев,
руководитель направления программирования в Яндекс.Практикуме
Помимо хорошей документации команда Доки планирует поддерживать и развивать сообщество веб-разработчиков. В планах — организовывать встречи и мероприятия, делать подкасты и видео для обмена знаниями.
Задача Доки — стать источником правды по веб-платформе для русскоязычного сообщества. В вебе есть много документации: от формальных спецификаций до развязных статей в личных блогах. Что найдёшь — тому и веришь. Как добавить свою каплю опыта в это море — не очень понятно. Плюс всё на английском языке, что становится не только барьером для тех, кто не знает язык, но и сдерживает тех, кто язык знает — нюансы часто теряются при чтении или переводе.
Другая сложность — как делиться опытом. Если напишешь пост в личный блог, даже на Хабр или Медиум, то высок шанс, что он потеряется со временем. Или даже хуже — не потеряется, но страшно устареет за пару лет. А тут можно так поделиться опытом, что это всегда будет на виду и любой сможет поправить то, что кажется некорректным.
Вадим Макеев,
главный редактор Доки
Как устроена Дока
Дока состоит из четырёх разделов: HTML, CSS, JavaScript и Инструменты.
В каждом разделе есть два типа статей. Дока — небольшая статья справочного характера. Статья — более объёмный материал, в котором автор рассуждает про какую-нибудь парадигму программирования, рассказывает о происхождении процесса, функции, тега.
Сейчас на сайте опубликовано 1011 статей.
Например, статья про grid
Команда проекта
Сейчас в команде 11 человек. Главный редактор проекта — Вадим Макеев, редактор разделов HTML и CSS — Алёна Батицкая, редактор разделов JavaScript и Инструменты — Николай Лопин, ревьюер разделов JavaScript и Инструменты — Саша Беспоясов, литературный редактор — Ольга Алексашенко.
Помимо редакторов, в команде Доки арт-директор Валя Броницкая, иллюстратор Кира Кустова, дизайнер Света Коробцева, бэкенд-разработчик Игорь Коровченко, фронтенд-разработчик Алексей Бузмаков и амбассадор в сообществе Егор Левченко.
Сотрудники Практикума стали вдохновителями проекта. Когда мы два года назад создавали программу по веб-разработке, то, во-первых, сами чувствовали нехватку в таком ресурсе, во-вторых, понимали, какую важную роль такой проект может сыграть и для сообщества, и для будущих разработчиков (которые сообщество дополнят).
Посмотрев по сторонам, поняли, что мы не одни с таким ощущением — так появилась команда, которая при поддержке Практикума довела проект до релиза. Основу команды составляет редакция. В начале, конечно, им пришлось многое сделать с нуля: собрать необходимую для запуска базу контента, сформировать редполитику, найти визуальный стиль, вплести в повествование инфографику и иллюстрации, сделать сайт. Параллельно мы показывали контент студентам Практикума, чтобы лучше понять, в правильную ли сторону двигаемся.
Теперь, после запуска, Практикум поддерживает независимую редакцию Доки, которая руководствуется своим желанием и целью сделать вместе с сообществом (и для сообщества) понятный, полезный и красивый справочник.
Сергей Нугаев,
руководитель направления программирования в Яндекс.Практикуме
Как принять участие в проекте
Дока — это опенсорс-проект, любой разработчик может написать статью, предложить уточнения и правки, помочь с развитием платформы. На странице проекта на GitHub можно подробно прочитать, как присоединиться к работе над Докой.
Дока во многом — эксперимент, так что мы, конечно же, хотим понять, пригодимся ли мы сообществу, будет ли просто и полезно контрибьютить в такую опенсорсную документацию. Это понятно, любой новый проект немного сомневается. Но мы уверены, что нужно развивать контент, описывать веб-платформу шире и глубже, запускать новые разделы. У нас уже есть мысли про раздел SVG по векторной графике, про доступность. Ну и, конечно, мероприятия, которые помогут нас лучше узнать и научиться контрибьютить в Доку — митапы и хакатоны, которые мы запустим уже в ближайшее время.
Вадим Макеев,
главный редактор Доки
Как устроена Дока — опенсорсный справочник с документацией, который сообщество пишет для сообщества
Дока — это справочник, который помогает начинающим разработчикам разобраться с нюансами веба, а более опытным даёт возможность делиться и обмениваться знаниями. Его особенность в том, что наполнением сайта занимается сообщество, а редакция Доки в этом помогает.
Недавно мы писали про запуск проекта, а в этом посте поговорим подробнее про его устройство. Редакторы Доки рассказали, сколько они работали над проектом, в чём отличия Доки от остальных справочников и почему важно формировать сообщество единомышленников.
Яндекс.Практикум поддерживает работу редакции Доки.
Что такое Дока и зачем она нужна
Алёна Батицкая, редактор разделов HTML и CSS: Дока — это опенсорсный проект, который будет развиваться и поддерживаться силами сообщества. Мы захотели написать классную документацию по веб-технологиям, максимально избегая технических терминов и показывая примеры использования той или иной функции или инструмента.
Николай Лопин, редактор разделов JavaScript и Инструменты: Дока — это документация для начинающих и продолжающих разработчиков. Её цель — дать понимание, как вообще работает веб, а не быть полной и объяснять всё супердетально. Другими словами, не фокусироваться на деталях, а дать высокоуровневое понимание того, что как функционирует.
Алёна: Глобальная цель Доки — передача знаний. Все, кто участвует в проекте, так или иначе были связаны с преподавательской деятельностью. Мы понимаем, что разные люди воспринимают информацию по-разному, поэтому важно делиться опытом на максимально высоком уровне качества и при этом простым языком.
Наша аудитория не ограничивается только студентами — к нам вполне могут приходить и действующие разработчики. Например, если кто-нибудь из бэкенда решил сверстать сайт, то он без проблем сможет это сделать, воспользовавшись нашей документацией.
Главная страница Доки. Навигация простейшая
Николай: Практически вся документация, которая есть в интернете, говорит на языке технических терминов. Для начинающих это очень сложный барьер: человек, который только учится разработке, запросто может потеряться в терминах, деталях и описаниях краевых случаев. Наша задача — поддержать их и показать, что в программировании работают не сверхлюди, а сложные вещи можно объяснять простым языком. Именно язык стирает дистанцию между читателем и автором документации.
Алёна: Важно, что все статьи на Доке — не перевод, а уникальный контент. Мы не переводим спецификацию или какие-то другие источники, а пишем всё с нуля. Вместе с информацией из официальных источников мы рассказываем и о собственном опыте.
Как пришла идея проекта
Алёна: Я довольно давно работаю в онлайн-образовании и много общаюсь со студентами. Они часто сталкиваются со сложностями при чтении англоязычных источников: либо им недостаточно их уровня английского, либо они не понимают, как работает веб. Так я начала переводить статьи, которые могли быть интересны моим студентам. Но даже для опытных разработчиков понятный текст на русском языке удобнее, чем официальная документация. Не всегда хочется погружаться и вникать в детали, особенно когда нужно что-то быстро подсмотреть.
Николай: Изначально мы были сайд-проектом Практикума и ориентировались на программу курсов по веб-разработке. Но в процессе работы мы поняли, что выходим за рамки методички для студентов, и нам захотелось создать большую справочную систему.
Дока направлена не на студентов конкретной школы. Бывают ситуации, когда человек уже давно занимается разработкой, но у него есть пробелы в отдельных областях. Дока может их закрыть на уровне интуитивного понимания проблемы, а за конкретным решением можно идти в документацию.
Алёна: Подобные проекты-справочники встречаются в русскоязычном сегменте, но у них есть свои недостатки.
Например, MDN — самый большой сборник документации. Там есть переводы определённых статей на русский язык, но в них злоупотребляют терминами. То есть если ты начинающий разработчик, джун или студент, то ты не сможешь сразу понять, что происходит. А ещё текст ломается при переводе на русский язык, потому что часто это машинный или неполный перевод. Если смотреть на русскоязычные аналоги — WebRef или HTMLbook, — в них всё представлено в максимально сжатом формате: свойство, что оно делает и набор значений.
Нам захотелось пойти глубже, потому что часто для понимания того, как работает свойство или тег, нужно чуть углубиться в то, как браузер обрабатывает это свойство. А ещё хорошо бы показать примеры, как это можно использовать в своей работе, — классные, яркие, интересные.
Иллюстрации помогают объяснить сложный материал, например вот статья о градиентах
Но наше самое большое отличие — блок «В работе». Суть этого блока в том, что мы уже не как авторы, а как разработчики делимся тем, как сами используем свойство, тег, функцию или что-то ещё для решения конкретных задач в своих проектах. Или рассказываем про какой-то баг, который не описан в спецификации, но если начать пользоваться тем, о чём говорится в статье, то этот баг обязательно всплывёт. То есть мы делимся накопленной мудростью. Это сильно отличает Доку от всех остальных проектов: нигде студент не может узнать такие нюансы, кроме как на собственном опыте, из рассказов ментора или преподавателя.
Так выглядит блок «В работе» в статье о тенях блока
Сколько прошло времени от идеи до релиза
Николай: У нас был идейный вдохновитель — Андрей Уродов. Это была его идея — собрать «добрую» документацию, где авторы разговаривают с читателем на понятном языке, а не на техническом. Постепенно эта идея оформилась: начинали мы с совсем уж панибратского стиля, но потом нашли хороший промежуточный вариант.
Алёна: Андрей пришёл ко мне с этой идеей три года назад. Она хоть и зародилась внутри Практикума, но на самом деле давно витала в воздухе внутри сообщества. Тогда мы начали собирать MVP на коленке, писали первые статьи в Notion и давали их посмотреть студентам. Отклик был позитивным, поэтому мы однозначно решили продолжать работу над этим проектом.
Какое-то время мы ещё писали в Notion, копили базу статей, потом сделали первый сайт, но в публичный доступ не выходили. Фоново мы отлаживали внутренние процессы: разделяли контент и код платформы, писали редакторскую политику, придумывали правила оформления, искали авторов, чтобы они помогали писать статьи. Так мы начали потихоньку разрастаться, крепчать и делать серьёзные шаги на пути к полноценному проекту.
Так выглядела Дока в самом начале
Николай: Большой пласт работы был сделан именно тогда, когда мы сами писали материалы и пытались их склеить с программой Практикума — на это ушёл год. Потом мы поняли, что странно оставлять проект только в рамках Практикума — нужно идти дальше.
Алёна — большой специалист по HTML и CSS, она закрыла эту часть. Я отобрал набор знаний по JavaScript, который считал необходимым минимумом, чтобы начинающий разработчик мог найти максимум информации в Доке и ему не нужно было идти куда-то ещё за дополнительной инфой. Сюда попало то, что могло пригодиться при подготовке к собеседованиям или при создании первых самостоятельных проектов.
Во время работы мы осознали, что современный веб не только про JavaScript, HTML и CSS — там гораздо больше всего. Особенно это заметно в больших проектах, где проявляется четвёртое измерение — инструменты, которые анализируют, как появляется сайт в интернете или как проверяется качество кода. Так в Доке выросло ещё одно направление, которое мы назвали «Инструменты». Это тот клей, который делает разрозненные куски кода приложением.
Алёна: Потом в команде начали появляться другие люди. Они выполняли те функции, которые мы не могли закрыть. Например, у нас появился литературный редактор Ольга Алексашенко, которая подчищала за нами все некрасивости и приводила тексты к единому стилю. Потом появился девопс Игорь Коровченко, который занимается автоматизацией, тестами и поиском. А когда дорисовали дизайн, мы нашли в команду талантливого разработчика Алексея Бузмакова, который реализовал очень непростой адаптивный интерфейс Доки и помог с движком Eleventy.
Николай: Сейчас мы релизимся, но у нас нет ощущения, что мы закончили. Документация по JavaScript и всему остальному — бездонный колодец, о котором можно писать вечно. Но мы стараемся приоритизировать темы и смотрим, что реально используется в индустрии. Дока должна отражать реальность разработки — это один из ключевых принципов, которым я руководствуюсь, делая выбор, о чём нужно рассказывать.
Кто ещё занимается Докой
Николай: У нас очень крутая команда. Она росла и изменялась, но главное, что в ней всегда были душевность и драйв. Мы с Алёной задаём стратегическое направление Доки, а курирует нас Вадим Макеев — фактический менеджер проекта.
Алёна: У нас есть отдел дизайна. Валя Броницкая помогает с общим дизайном контента, иллюстратор Кира Кустова рисует бомбические картинки к нашим статьям, а Света Коробцева занимается дизайном демок. Демки — это наша гордость. Они помогают визуализировать то, о чём мы пишем.
Пример статьи с демкой, в которой мы рассказываем про размер фона. В ней можно переключать значения, чтобы понять, как работает это свойство
Раньше мы работали с авторами, которые помогали нам писать статьи. Они нам очень помогли собрать основу, потому что было бы странно запускать справочник с минимумом информации. Сейчас мы релизнулись и планируем, что Дока будет развивается силами сообщества.
Как устроена работа над статьями
Алёна: Как всё будет работать на самом деле, ещё пока никто не знает, но у нас есть план. Опенсорсный проект предполагает, что в него может зайти любой человек, кому это интересно и кому хочется поделиться опытом. Дальше мы смотрим новый материал на предмет технических ошибок — нет ли грубых расхождений со спецификацией. Мы оставляем автору комментарии, обсуждаем ту или иную правку. Когда все комментарии согласованы, приходит редактор и правит текст с точки зрения русского языка. Когда статья проходит все эти этапы, она попадает на сайт. А если в ней есть картинки и демки, дизайнеры отрисовывают их, когда статья уже опубликована. Всё открыто и прозрачно.
Наш репозиторий на Гитхабе
Николай: В отношении иллюстраций и других доработок у нас работает простое правило: если текст уже достаточно хорош и приносит пользу, то мы публикуем статью, а дальше дорабатываются остальные сопутствующие материалы. Мы не блокируем процесс релиза статьи этими вещами. Пусть текст будет опубликован с черновыми схемами, но им уже будут пользоваться люди — остальное доедет постепенно.
Алёна: Наверняка будут ситуации, когда люди будут исправлять что-то в текущих статьях. Например, если захотят уточнить формулировку или обновить информацию о какой-нибудь функции. Человек создаёт пул-реквест, мы оцениваем, насколько это актуальная правка и нужна ли она нам. Дальше запускаются те же процессы, как и при публикации статьи.
Всех авторов, которые написали статью или внесли значимые правки, мы указываем в контрибьюторах. Другими словами, у нас нет политики «смерти автора». Поскольку мы опенсорсный проект силами сообщества, мы будем стараться всячески задаривать плюшками активных участников. Пусть пока и в виде упоминания, но позже придумаем что-то поинтереснее.
Николай: Ещё у нас есть список материалов, которые хотелось бы увидеть на сайте, — ишью на Гитхабе. Этот список доступен всем, поэтому любой заинтересованный человек может написать свою статью. Мы постараемся всё обсудить заранее, поможем составить план и верхнеуровнево обсудить, о чём нужно написать.
Алёна: Сейчас разделы в Доке уже неплохо заполнены: в разделе HTML 161 статья, CSS — 448, JavaScript — 328, Инструменты — 164. В общей сложности сейчас на сайте опубликовано 1011 статей (данные на момент записи интервью — Прим. ред.).
У нас есть три типа статей. Дока — это небольшая статья справочного характера. В ней есть теги и свойства, про которые много не напишешь, поэтому мы просто рассказываем, как это работает или зачем это нужно.
Есть формат статьи, где автор рассуждает про какую-нибудь парадигму программирования. Как правило, это объёмный материал, в котором рассказывается о происхождении какого-нибудь процесса, функции, тега, где это всё применяется и как работает в больших проектах.
Третий тип статей — плейсхолдеры. Это суперкороткая выжимка: что это за свойство, тег или метод и какие у него есть значения или атрибуты. Формат временный: мы его сделали к запуску, когда поняли, что не успеваем написать обо всём. Нам хочется, чтобы человек не расстраивался, если что-то искал в Доке и в итоге не нашёл. Пусть он лучше найдёт краткую, но, возможно, достаточную для работы информацию вместо ошибки 404. На плейсхолдерах есть плашка, что эта статья пока не закончена, вы можете написать её сами.
Так выглядит плейсхолдер. В шапке статьи есть прямая ссылка на репозиторий
Какой будет Дока
Алёна: У нас амбициозные планы. Мы очень хотим стать чем-то вроде настольной книги разработчика, тем местом, куда люди будут приходить, когда им нужно будет найти ответ на вопрос или освежить знания.
Сейчас нам нужно закрыть все плейсхолдеры. После этого хотим развивать другие разделы — мы не ограничимся теми четырьмя, которые есть сейчас. Мне бы очень хотелось запустить раздел по SVG, потому что это отдельный язык векторной графики в браузере со своими особенностями. Ещё думаю о разделе по доступности: например, чтобы сайты были читабельны скринридерами, нужно их правильно настроить. Пока такого источника по доступности, в который можно обратиться в любой момент и всегда найти там ответ, на горизонте нет.
Очень хотелось бы, чтобы сообщество поняло пользу проекта и поддержало нас своими силами. Нужно, чтобы люди приходили и дописывали или правили какие-то штуки, делились своим опытом в блоке «В работе».
Николай: Без сообщества Дока, конечно, невозможна. Наша задача — создавать его вокруг этого проекта. Но сообщество не создашь написанием статей и комментариями. Здесь нужно постоянное общение, которое нужно поэтапно выстраивать. Важно не быть стеной, за которую закидывают статью, а потом она оттуда возвращается с правками. Нужно быть максимально открытыми, и с точки зрения обратной связи от сообщества, и с точки зрения общения.
Алёна: Да, взаимодействие с сообществом предполагает открытость, и мы хотим делиться знаниями не только в формате Доки, но ещё устраивать митапы и, может быть, даже организовать «Докафест» по примеру «Хактоберфеста». Кроме этого хочется делать какие-то фан-проекты на стыке технологий, которые не относились бы только к одному определённому разделу. Например, какой-нибудь проект по анимации сайтов.
Николай: Я верю, что нам удастся собрать сообщество, и у нас будет такая тусовка, где людям интересно помогать другим с помощью документации или как-нибудь ещё. Мне нравится думать о Доке как о платформе обмена знаниями и опытом. Я вижу серьёзный потенциал проекта — он даст гораздо больше, чем любая техническая документация.
Значение слова «док»
Источник (печатная версия): Словарь русского языка: В 4-х т. / РАН, Ин-т лингвистич. исследований; Под ред. А. П. Евгеньевой. — 4-е изд., стер. — М.: Рус. яз.; Полиграфресурсы, 1999; (электронная версия): Фундаментальная электронная библиотека
Корабельный док — сооружение, предназначенное для постройки, транспортировки (плавучий док), ремонта и окраски судов, а также для их погрузки и выгрузки.
Док, Клемент Мартин — южноафриканский лингвист, африканист, один из крупнейших специалистов по языкам банту первой половины XX века.
Док (программа) — часть компьютерного графического интерфейса, вариант панели инструментов.
Док — сокр. от доктор, неофициальное обращение к врачам и учёным, употребляется во многих художественных фильмах в качестве прозвища.
ДОК — деревообрабатывающий комбинат.
ДОК, дока, м. [англ. dock]. Портовое сооружение, в к-рое вводятся суда для ремонта. Плавучий д. Сухой д.
Источник: «Толковый словарь русского языка» под редакцией Д. Н. Ушакова (1935-1940); (электронная версия): Фундаментальная электронная библиотека
док I
1. портовое сооружение для постройки, осмотра и ремонта судов
Фразеологизмы и устойчивые сочетания
док II
Делаем Карту слов лучше вместе
Привет! Меня зовут Лампобот, я компьютерная программа, которая помогает делать Карту слов. Я отлично умею считать, но пока плохо понимаю, как устроен ваш мир. Помоги мне разобраться!
Спасибо! Я стал чуточку лучше понимать мир эмоций.
Вопрос: масличный — это что-то нейтральное, положительное или отрицательное?