На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- WordPress
- Технический писатель:
- молчаливый
- Название проекта:
- Полный и обновленный набор документации по стилю.
- Длина проекта:
- Длительный ход (5 месяцев)
Описание Проекта
Краткое описание:
WordPress — это глобальная некоммерческая организация по разработке программного обеспечения, целью которой является предоставление мировому сообществу программного обеспечения, в котором особое внимание уделяется доступности, производительности, безопасности и простоте использования. Целью WordPress является демократизация публикации и программного обеспечения с открытым исходным кодом в Интернете. В наш цифровой век веб-сайт в буквальном смысле слова является онлайн-фасадом организации/частного лица; и WordPress выполняет огромную задачу по эффективному обслуживанию сотен миллионов пользователей (что соответствует 35% Интернета, которым он управляет) с помощью своего программного обеспечения. Для дальнейшего эффективного обслуживания этих пользователей необходима документация, которая используется большинством разработчиков, администраторов и конечных пользователей. Таким образом, документацию можно считать основным фактором экосистемы WordPress. Текущая документация WordPress не включает универсальный и унифицированный набор правил и рекомендаций по стилю для публикации. Целью этого предложения является создание полного и обновленного набора рекомендаций по стилю документации, универсально применимого для документации WordPress. Идея проекта предполагает объединение всех аспектов рекомендаций по дизайну и стилю, таких как семантика, синтаксика, грамматические рекомендации, пунктуация, правила, специфичные для разработки, атрибуты дизайна и особенности форматирования. Он также включает в себя языковые соглашения, такие как залог, тон, время, все части речи, а также соглашения об именах. В качестве инструментов, языков и платформ будут использоваться WordPress CMS, GitHub, Markdown, а также могут использоваться PHP/MySQL, HTML/CSS и JavaScript.
План проэкта:
Текущее состояние руководств по стилю документации WordPress. Команда документации WordPress внедрила необъявленную, но единодушную методологию руководств по публикации. Но время от времени некоторые элементы предполагаются, и процесс становится умозрительным. Не существует какого-либо фиксированного стандарта и критерия написания и публикации статей для WordPress. Группа документации разработала рекомендации по стилю для конкретного проекта, но ни одно из них не является универсальным. Большинство существующих руководств по стилю не объединены в одном справочнике или устарели и нуждаются в обновлении. Следовательно, существует необходимость спроектировать и разработать единое руководство по стилю для стандартизации документации WordPress.
Цели:
Более 35% веб-сайтов в Интернете работают на WordPress, что, в свою очередь, указывает на то, что миллионы разработчиков и конечных пользователей используют впечатляющие функциональные возможности WordPress. Документация является важным элементом, помогающим разработчикам и пользователям эффективно выполнять эти функции без каких-либо проблем, даже в случае возникновения неудобств. Общая цель этого проектного предложения — стандартизировать руководство по дизайну и стилю, унифицировать и обновить существующие руководства по стилю, а также добавить новые правила и спецификации для документации WordPress. Это обеспечит простоту использования, простоту и единообразие документации WordPress.
Выполнение:
Как предложил наставник (Джон Энг) этого проекта, проект можно реализовать в 4 этапа: этап открытия, определения, внедрения и обслуживания. Перед началом проекта, в течение периода подготовки к стажировке, я буду работать со своим наставником и согласовывать подходящий график и график, соответствующий моему последующему графику и результатам. Далее я ознакомлюсь с системой WordPress и протоколами работы данного проекта.
В начале стажировки я обсужу и составлю краткое изложение плана со своим наставником. Будут определены требования и потребности. Во-первых, я опишу поток документации и процесс взаимодействия с пользователем. Впоследствии будут обрисованы макеты каждого раздела, категории и компонента. Эти макеты затем будут рассмотрены моим наставником. При необходимости макеты будут переработаны, а некоторые компоненты добавлены/удалены. Затем я проведу исследование пользователей для определения удобства использования и осуществимости интерфейса. Впоследствии Руководство по стилю документации будет реализовано (как показано на диаграмме ниже) для каждого раздела. В качестве дополнения к нашему руководству можно также использовать руководства по стилю других организаций, которые пользуются лицензиями с открытым исходным кодом или Creative Commons. Если в течение этого периода возникнут какие-либо трудности с юзабилити, я их переделаю.
Тестирование и оптимизация будут проводиться после того, как руководство по стилю будет завершено и интегрировано с HelpHub. Любые уязвимости, избыточные элементы или компоненты будут устранены. Будет проведено тестирование пользовательского интерфейса и кода и, если потребуется, исправлены нежелательные ошибки и ошибки. Окончательный контроль качества полного руководства по стилю будет проводиться на предмет языка, грамматики, орфографии, пунктуации и т. д.
Задачи, ожидающие выполнения из-за непредвиденных задержек, будут завершены в течение буферного периода. Дополнительные функциональные возможности или функции, которые будут признаны возможными в ходе проекта, могут быть реализованы после завершения окончательного тестирования. Будет составлен план развертывания и представлен готовый продукт.
Инструменты и методологии:
Документация будет компилироваться и редактироваться на совместной платформе, например Google Docs. Если требуется публикация через GitHub, также можно реализовать языки разметки, такие как Markdown или GitHub Flavored Markdown. Что касается стандартов дизайна и стиля, можно также обратиться к рекомендациям по стилю с открытым исходным кодом. Наконец, готовый документ будет отформатирован и опубликован с использованием WordPress.
Таблица компонентов:
Это исчерпывающий список компонентов, которые можно реализовать в Руководстве по стилю. Рекомендации по документированию: доступность, структура документа, кодировка, внешние источники, факты, шрифты, глобальная аудитория, инклюзивность, легальность, доступность для нескольких платформ, однозначность, отсутствие чрезмерных претензий, макет страницы, политическая корректность, протоколы, безопасность, структура предложения, Краткое письмо, тон и стиль, беспристрастность
Язык и грамматика: сокращения и акронимы, утверждения и отрицания, артикли, использование заглавных букв, предложение, прямая/косвенная речь, первое/второе/третье лицо, роды, глоссарий, существительные, префиксы и суффиксы, предлоги, местоимения, ссылки, сленг и жаргон, Правописание, Технические термины, Время, Глаголы, Залог
Пунктуация — апостроф и кавычки, двоеточия и точки с запятой, запятые, многоточия, восклицательные знаки, дефисы и тире, круглые скобки, точки, вопросительные знаки, косая черта
Форматирование — тезисы, введение, предисловия, торговые марки, названия продуктов, подписи, фрагменты кода, блоки кода, дата и время, часовые пояса, места, валюты, имена файлов, сноски, заголовки и названия, выделение (жирным шрифтом, курсивом, подчеркиванием, Зачеркивание, Цитата), Отступы, Указатель, Ссылки и URL-адреса, Списки, Маркированные списки, Нумерация, Медиа (изображения, видео) и иллюстрации, Примечания, Предупреждения, Советы, Числа и номера телефонов, Полиглоты, Перевод, Языковые сценарии, Интервалы, Таблицы , Текст, Товарные знаки, Авторские права, Патенты, Цитаты, Учебные пособия и процедуры, Элементы пользовательского интерфейса, Единицы измерения
Пользовательский интерфейс: действия, кнопки, фрагменты кода, блоки кода, интерфейс командной строки, диалоги, меню и раскрывающиеся списки, всплывающие окна и оповещения, вкладки, терминология, элементы пользовательского интерфейса, Windows
Код — CSS, HTML, JS, Markdown, MySQL, PHP, синтаксис, XML
Словарь употребления слов/глоссарий – от А до Я