Участие в веб-документах MDN

MDN Web Docs документирует веб-платформу уже более двенадцати лет и в настоящее время представляет собой межплатформенную работу с вкладами и Консультативным советом, в состав которого входят представители Google, Microsoft и Samsung, а также представители Firefox. Что является фундаментальным для MDN, так это то, что это огромные усилия сообщества, при этом веб-сообщество помогает создавать и поддерживать документацию. В этой статье я собираюсь дать вам несколько советов относительно мест, где вы можете внести свой вклад в MDN, и как именно это сделать.

Если вы раньше не участвовали в проектах с открытым исходным кодом, MDN — отличное место для начала. Необходимые навыки варьируются от редактирования текста, перевода с английского на другие языки, навыков работы с HTML и CSS для создания интерактивных примеров или интереса к совместимости браузеров для обновления данных о совместимости браузеров. Что вам не нужно делать, так это писать много кода, чтобы внести свой вклад. Это очень просто и отличный способ отблагодарить сообщество, если вы нашли эти документы полезными.

Участие в страницах документации

В первую очередь вы можете внести свой вклад в саму документацию MDN. MDN — это вики, поэтому вы можете войти в систему и начать помогать, исправляя или добавляя любую документацию по CSS, HTML, JavaScript или любой другой части веб-платформы, охватываемой MDN.

Чтобы начать редактирование, вам необходимо авторизоваться с помощью GitHub. Как обычно в вики, перечислены все редакторы страницы, и в этом разделе будет использоваться ваше имя пользователя GitHub. Если вы посмотрите на любую из страниц MDN, участники перечислены внизу страницы, на изображении ниже показаны текущие участники страницы в CSS Grid Layout.

Что вы можете редактировать?

Вещи, которые вы могли бы рассмотреть как редактор, это исправление очевидных опечаток и грамматических ошибок. Если вы хороший корректор и редактор текстов, вы вполне можете улучшить читабельность документов, исправив любые орфографические или другие ошибки, которые вы обнаружите.

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

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

Еще одно место, которое вы можете добавить на страницу, — это добавление ссылок «См. также». Это могут быть ссылки на другие части MDN или на внешние ресурсы. При добавлении внешних ресурсов они должны быть тесно связаны со свойством, элементом или методом, описываемым в этом документе. Хорошим кандидатом было бы учебное пособие, демонстрирующее, как использовать эту функцию, что-то, что даст читателю, ищущему информацию, ценный следующий шаг.

Как редактировать документ?

После входа в систему вы увидите ссылку «Редактировать на страницах» в MDN, нажав на нее, вы перейдете в WYSIWYG-редактор для редактирования контента. Ваши первые несколько правок, скорее всего, будут небольшими изменениями, и в этом случае вы сможете следовать своему чутью и редактировать текст. Если вы вносите обширные изменения, то стоит сначала взглянуть на руководство по стилю. Существует также руководство по использованию редактора WYSIWYG.

После внесения изменений вы можете просмотреть, а затем опубликовать. Перед публикацией рекомендуется объяснить, что вы добавили и почему, используя поле «Комментарий к редакции».

Языковые переводы

Тем из нас, для кого английский является родным языком, невероятно повезло, когда дело доходит до информации в Интернете, поскольку они могут получить почти всю информацию, которую мы когда-либо хотели, на нашем родном языке. Если вы можете переводить англоязычные страницы на другие языки, вы можете помочь с переводом веб-документов MDN, сделав всю эту информацию доступной большему количеству людей.

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

Интерактивные примеры

Интерактивные примеры на MDN — это примеры, которые вы увидите в верхней части многих страниц MDN, например, этот для свойства grid-area .

Эти примеры позволяют посетителям MDN опробовать различные значения свойств CSS или опробовать функцию JavaScript прямо в MDN без необходимости заходить для этого в среду разработки. Проект по добавлению этих примеров продолжается уже около года, вы можете прочитать о проекте и достигнутом прогрессе в публикации «Приведение интерактивных примеров в MDN».

Содержимое этих интерактивных примеров хранится в репозитории интерактивных примеров GitHub. Например, если вы хотите найти пример для области сетки, вы найдете его в этом репозитории в разделе live-examples/css-examples/grid . В этой папке вы найдете два файла для grid-area , файл HTML и файл CSS.

сетка-area.html

 <section class="example-choice-list large" data-property="grid-area"> <div class="example-choice" initial-choice="true"> <pre><code class="language-css">grid-area: a;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: b;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: c;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: 2 / 1 / 2 / 4;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> </section> <div class="output large hidden"> <section class="default-example"> <div class="example-container"> <div class="transition-all">Example</div> </div> </section> </div>

grid.area.css

 .example-container { background-color: #eee; border: .75em solid; padding: .75em; display: grid; grid-template-columns: 1fr 1fr 1fr; grid-template-rows: repeat(3, minmax(40px, auto)); grid-template-areas: "aaa" "bcc" "bcc"; grid-gap: 10px; width: 200px; } .example-container > div { background-color: rgba(0, 0, 255, 0.2); border: 3px solid blue; } example-element { background-color: rgba(255, 0, 200, 0.2); border: 3px solid rebeccapurple; }

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

Затем создайте ветку и отредактируйте или создайте новый пример. Когда вы будете довольны этим, отправьте запрос на включение в репозиторий интерактивных примеров, чтобы попросить проверить ваш пример. Чтобы примеры были согласованными, обзоры довольно придирчивы, но должны четко указывать на изменения, которые вам необходимо внести, чтобы вы могли обновить свой пример и утвердить его, объединить и добавить на страницу MDN.

Теперь, когда почти весь CSS покрыт (в дополнение к примерам JavaScript), MDN ищет помощи в создании примеров HTML. Инструкции о том, как начать работу, приведены в сообщении на форуме MDN Discourse. Ознакомьтесь с этим постом, так как он содержит ссылки на документ Google, который вы можете использовать, чтобы указать, что вы работаете над конкретным примером, а также некоторую другую полезную информацию.

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

Данные совместимости браузера

Совсем недавно данные о совместимости браузеров, перечисленные на страницах MDN, начали обновляться в рамках проекта совместимости браузеров. Этот проект разрабатывает данные совместимости браузеров в формате JSON, которые могут отображать таблицы совместимости в MDN, но также могут быть полезными данными для других целей.

Данные о совместимости браузера находятся на GitHub, и если вы обнаружите страницу с неверной информацией или все еще использует старые таблицы, вы можете отправить запрос на извлечение. Репозиторий содержит информацию о вкладе, однако самый простой способ начать — отредактировать существующий пример. Недавно я обновил информацию о свойстве CSS shape-outside . В ресурсе уже были некоторые данные в новом формате, но они были неполными и неправильными.

Чтобы отредактировать эти данные, я сначала разветвил данные совместимости браузера, чтобы у меня была своя собственная развилка. Затем я клонировал это на свою машину и создал новую ветку, чтобы внести свои изменения.

Как только у меня появилась новая ветка, я нашел файл JSON для shape-outside и смог внести свои изменения. У меня уже было хорошее представление о поддержке этого свойства браузерами; Я также использовал живой пример на странице формы вне MDN, чтобы проверить наличие поддержки, когда я не был уверен. Таким образом, внесение изменений было связано с работой с файлом, проверкой номеров версий, перечисленных для поддержки свойства, и обновлением тех, которые были неверны.

Поскольку файл имеет формат JSON, его довольно просто редактировать в любом текстовом редакторе. Файл .editorconfig объясняет простые правила форматирования для этих документов. В этом контрольном списке также есть несколько полезных советов.

После того, как вы внесли свои изменения, вы можете зафиксировать свои изменения, отправить свою ветку в свою вилку, а затем сделать запрос на включение в репозиторий данных совместимости браузера. Вполне вероятно, что, как и в случае с живыми примерами, рецензент предложит вам внести некоторые изменения. В моем PR для данных Shapes у меня было несколько ошибок в том, как я помечал данные, и мне нужно было внести некоторые изменения в ссылки. Это было просто сделать, а затем мой PR был объединен.

Начать

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

Если вы никогда раньше не отправляли запрос на вытягивание проекта, это очень удобное место для первого PR, и, надеюсь, я показал, что есть способы внести свой вклад, которые вообще не требуют написания кода. Очень ценным навыком для любого проекта документации является умение писать, редактировать и переводить, поскольку эти навыки могут помочь сделать техническую документацию более легкой для чтения и доступной для большего числа людей во всем мире.