Эта страница переведена с помощью Cloud Translation API.

проект ESLint

На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.

Краткое описание проекта

Организация с открытым исходным кодом:: ESLint
Технический писатель:: Хавар
Название проекта:: Реорганизовать/переписать конфигурационную документацию
Длина проекта:: Стандартная продолжительность (3 месяца)

Описание Проекта

Абстрактный

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

Краткое описание проекта Документация по настройке ESLint (https://eslint.org/docs/user-guide/configuring) в ее текущем состоянии предоставляет много информации на одной странице. Несмотря на наличие на странице заголовков, подзаголовков и соответствующих абзацев, документация может оказаться непосильной. Невозможно перейти к определенному разделу страницы, что расстраивает пользователя, интересующегося конкретным разделом. Информация из-за такой неорганизованности также может потеряться, не выполняя своей цели и требуя от пользователей дополнительных усилий.

Однако эти проблемы можно решить с помощью ряда осторожных шагов. Я предлагаю провести аудит контента в качестве первого шага в этой реорганизации. Аудит контента не только поможет выявить проблемы в подаче информации, но и высветит недостатки самого контента (например, устаревшую или неполную информацию). Затем я планирую создать информационную архитектуру (IA), чтобы раскрыть сеть знаний. Это позволит нам группировать информацию по различным темам и находить связи между различными тесно связанными темами. Информация, полученная с помощью этих двух практик, затем будет использоваться для разделения одностраничной документации на несколько страниц. Затем весь пакет можно связать и дать перекрестные ссылки в Markdown. В результате появится более организованная версия документации по конфигурации, в которой будет легче ориентироваться и понимать.

Мотивация Несмотря на то, что я использую программное обеспечение с открытым исходным кодом уже довольно давно, мое знакомство с этим термином довольно новое, аналогично моим знаниям о программном обеспечении для линтинга. Когда я начал изучать Python (через edX), я задавался вопросом, как крошечные ошибки могут испортить весь код. Я подумал, что было бы неплохо каким-то образом протестировать ваши коды и выявить ошибки, а затем я узнал о термине «линтинг». Я еще не использовал программное обеспечение для линтинга, но уверен, что в будущем оно значительно облегчит мне жизнь.

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

Цели Основная цель этого проекта — обеспечить, чтобы документация на странице конфигурации ESLint была простой для понимания и не перегружала пользователей. Для успеха проекта важно, чтобы навигация по контенту была простой и свободной от каких-либо сложностей. Важными целями проекта являются следующие. - Проведение комплексного аудита контента - Создайте информационную архитектуру для понимания потока информации - Улучшите информационную архитектуру для реорганизации документации - Определите связи и ссылки между различными разделами контента - Перепишите/редактируйте части документации, если необходимо, чтобы они соответствовали требования к реконфигурации

- Убедитесь, что контент является гибким и пригодным для повторного использования.

Описание проекта Настройка ESLint — важная функция, которая делает ESLint настраиваемым. Пользователи, заинтересованные в настройке, наверняка будут заинтересованы в одном или двух аспектах одновременно. Поэтому важно, чтобы пользователь ориентировался на конкретную интересующую его тему, обеспечивая тем самым эффективное решение. Текущая версия документации по настройке ESLint содержит много полезной информации, но она организована таким образом, что пользователи могут почувствовать себя ошеломленными, разочарованными и потерянными. Например, если кто-то хочет узнать об использовании сторонних плагинов в ESLint, ему придется прокрутить вниз обсуждение определения парсера, сред и глобальных переменных. Вся эта практика утомительна для пользователей и может оттолкнуть их от сайта. Аналогично, если пользователь находится где-то посередине страницы и хочет перейти в определенный раздел или просто просмотреть похожие темы, для него это будет непростой задачей, поскольку никакой такой помощи пользователям не предоставляется. Эти вопросы требуют немедленного внимания, поскольку качество любой документации, независимо от того, насколько хорошо она составлена, зависит от ее полезности. Я предлагаю решения этих и других связанных с ними вопросов в последующем обсуждении.

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

Создание информационной архитектуры Чтобы понять сеть знаний или поток информации в документации по конфигурации, может оказаться полезным создание информационной архитектуры (IA). Результаты аудита контента послужат хорошей основой для понимания и развития потока информации. Затем будет создана улучшенная версия IA для лучшей организации и представления документации. Этот улучшенный IA не только реструктурирует текущий контент, но также определит связи и ответвления между различными разделами документации, создавая тем самым эффективную сеть. Например, за содержимым раздела «Настройка правил» может идти ссылка, ведущая на «Отключение правил со встроенными комментариями». Другие подобные ссылки также могут быть идентифицированы, создавая таким образом связи между различными разделами документации.

Аудит содержания и IA предоставят достаточную информацию для создания подробного оглавления со ссылками, ведущими к конкретным разделам и подразделам документации. Создание отдельных файлов для каждого раздела и добавление соответствующих ссылок на другие разделы может повысить ценность всего набора документов. Оглавление может быть создано для пользователей, просматривающих документацию по конфигурации, что облегчает их работу на веб-сайте. Оглавление может включать все заголовки первого и второго уровня, чтобы оно было кратким, но всеобъемлющим. Например, одна из таких практик используется Prettier (https://prettier.io/docs/en/index.html) для организации документации.

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

Инструменты для использования Некоторые важные инструменты, которые могут пригодиться во время работы над проектом: - Draw.io для создания иллюстраций для IA по мере необходимости - Atom (или аналогичный редактор) для написания и редактирования документов в Markdown

- GitHub для обеспечения контроля версий документации.

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

10 июля 2020 г. — 16 августа 2020 г.: Рассмотрение и отбор предложений. Я просматриваю документацию ESLint и развиваю навыки, необходимые для завершения проекта (например, написание Markdown, сотрудничество на GitHub). Я также буду участвовать в разработке документации через GitHub и общаться с другими людьми, чтобы лучше понять документацию.

17 августа 2020 г. — 13 сентября 2020 г.: Сплочение сообщества. В течение периода сплочения сообщества я буду дорабатывать свое предложение в соответствии с обсуждениями с наставниками и заинтересованными командами. При необходимости я также отредактирую цели и этапы. Кроме того, я обязательно составлю список инструментов, которые затем будут использоваться для работы над проектом.

14 сентября 2020 г. - 19 сентября 2020 г.: Контент-аудит Для начала проекта я проведу комплексный контент-аудит конфигурационной документации. Цель будет заключаться в том, чтобы подчеркнуть проблемы, связанные с содержанием и его представлением.

20 сентября 2020 г. - 25 сентября 2020 г.: Информационная архитектура (IA). После аудита контента я создам IA конфигурационной документации. Я сосредоточусь на том, чтобы представить сеть знаний в доступной для понимания форме. Это поможет улучшить поток информации.

26 сентября 2020 г. — 30 сентября 2020 г.: Ссылки и ссылки. На этом этапе я проанализирую IA, чтобы определить связи и ссылки между различными разделами документации. Я также создам иерархию всех разделов, тем самым улучшив IA в процессе.

1 октября 2020 г. — 3 октября 2020 г.: Окончательная карта. С помощью информации, полученной в ходе аудита контента и IA, я затем создам окончательную карту, которая будет реализована в реорганизованной документации по конфигурации. Эта подробная карта будет содержать оглавление, иерархию тем, а также список ссылок и перекрестных ссылок между разделами документации.

4 октября 2020 г. — 5 октября 2020 г.: Обсуждение На этом этапе, то есть перед редактированием документации, я представлю свои выводы и план наставникам и заинтересованным командам. Их отзывы помогут уточнить план и внести изменения, где это необходимо.

06 октября 2020 г. - 20 октября 2020 г.: Переписывание и редактирование. В этот период я буду редактировать и обновлять те разделы документов, где требуется доработка. Некоторые разделы конфигурационной документации могут быть переписаны или в нее могут быть добавлены новые элементы. На этом этапе основное внимание будет уделяться обеспечению точности, обновления, гибкости и возможности повторного использования документации.

21 октября 2020 г. - 25 октября 2020 г.: Исправления и ссылки. На этом этапе я проверю свою работу, чтобы избавиться от грамматических и структурных ошибок, а также перепроверить свою работу на точность. Я также добавлю ссылки и ссылки между разделами согласно IA, чтобы документация соответствовала карте знаний, разработанной ранее.

26 октября 2020 г. — 31 октября 2020 г.: окончательная версия для отправки. Я свяжу все файлы Markdown, создам оглавление и поделюсь черновиками с наставниками. Это послужит представлением первого проекта в виде полного пакета.

01 ноября 2020 г. — 5 ноября 2020 г.: Первый обзор. В течение этих пяти дней я буду обсуждать первый вариант со своими наставниками. Я получу их отзывы и обсужу с ними свои идеи, чтобы составить список правок, которые необходимо внести.

06 ноября 2020 г. - 12 ноября 2020 г.: Первые правки С помощью отзывов наставников я отредактирую первый черновик документации. Фактические правки будут зависеть от характера комментариев и отзывов, но целью этапа редактирования будут цели повторного использования, точности и гибкости.

13 ноября 2020 г. — 15 ноября 2020 г.: Вторая проверка. После завершения первоначальных правок я еще раз обсужу прогресс со своими наставниками и заинтересованными командами. Эти обсуждения будут сосредоточены на изменениях, внесенных в первую версию, а также на других проблемах, которые могли возникнуть в процессе редактирования.

16 ноября 2020 г. — 19 ноября 2020 г.: Второе редактирование. Затем я посвятю четырехдневный период редактированию документа. Полученные в результате версии будут обсуждаться с наставниками для придания им окончательной формы. По завершении этого этапа документы будут в окончательной форме и готовы к загрузке на веб-сайт и в репозиторий GitHub.

20 ноября 2020 г. - 23 ноября 2020 г.: Размещение на сайте. После внесения всех необходимых правок документы будут загружены на сайт. Любые проблемы, возникающие в процессе, будут решены соответствующим образом, поскольку у нас еще будет несколько дней для работы над документацией.

24 ноября 2020 г. – 28 ноября 2020 г.: Отчет о проекте В течение этого пятидневного периода будет создан подробный отчет о проекте. Представленные цели, трудности, проблемы и решения станут частью отчета о проекте. Отчет будет передан наставникам для обратной связи.

29 ноября 2020 г. – 30 ноября 2020 г.: Окончательная подача проекта. Проект вместе со всеми файлами и отчетом по проекту будет отправлен наставникам. Обзор всего проекта будет проводиться посредством встречи/обсуждения с наставниками и заинтересованными командами.

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

Обо мне У меня есть степень бакалавра в области электротехники и степень магистра в области технических и профессиональных коммуникаций Университета штата Северная Каролина. У меня есть опыт работы в области технического и профессионального написания и редактирования, коммуникации и управления контентом, исследований удобства использования веб-сайтов и мобильных устройств, а также разработки инструкций. Я работал заместителем редактора онлайн-издания (Global Village Space) и стажером по связям с общественностью в компании Duke Forge в Университете Дьюка. Наряду с этим у меня также есть интерес к творческому письму.