На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- HPX
- Технический писатель:
- рстобо
- Название проекта:
- Редактирование и оптимизация существующей документации HPX
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание Проекта
Мое предложение — отредактировать и оптимизировать содержание существующей документации HPX. Мое предложение касается проекта на стандартный срок (три месяца), который фокусируется на пересмотре двух глав руководства группы STE||AR: «Система сборки и запуск HPX» (1) и «Настройка приложений HPX» (2). .
Глава «Система сборки и запуск HPX» содержит несколько грамматических ошибок, а также содержит запутанный язык и непоследовательное использование заглавных букв таких терминов, как «CMake». Более того, он содержит повторяющуюся информацию, которую я планирую переупорядочивать, консолидировать и сокращать по мере необходимости. Хотя глава «Настройка приложений HPX» также содержит несколько грамматических ошибок, которые необходимо исправить, в этой главе меня больше всего беспокоит ее удобство для пользователя. В этой главе я планирую затронуть три основные проблемы проектирования:
Некоторые заголовки спрятаны в тексте, что затрудняет беглый просмотр главы. В настоящее время пользователю необходимо внимательно прочитать руководство, чтобы понять назначение каждой таблицы. Большинство пользователей не так взаимодействуют с инструкциями по эксплуатации, особенно если они уже прочитали их содержимое раньше. Вместо этого я планирую убедиться, что каждая таблица имеет четкий и четкий заголовок, который можно легко увидеть, если пользователь прокручивает текст.
При перечислении различных свойств под определенным заголовком свойства не следуют в логическом порядке. Хотя свойства сгруппированы по общей теме, подгрупп нет, из-за чего информация кажется разрозненной. Например, пользователь может столкнуться с несколькими свойствами, связанными с местоположением, несколькими, связанными с другим предметом, а затем еще одним, связанным с местоположением. Отсутствие внутренней структуры заголовков затрудняет поиск всей информации по конкретной подтеме. Поэтому я планирую реорганизовать несколько диаграмм, чтобы более четко сгруппировать схожую информацию под каждым заголовком.
Пользователям приходится перемещаться между разделами вперед и назад (или открывать руководство на двух отдельных вкладках), чтобы полностью понять определенные инструкции. Есть моменты, когда глава направляет пользователя к одному предложению в предыдущем разделе таким образом, что читателю приходится прокручивать вверх или переходить по гиперссылке, чтобы понять точную инструкцию, поскольку в руководстве используются расплывчатые формулировки типа «этот шаг выполняется после шаг 11» в предыдущем разделе. Хотя этот метод устраняет повторение, он затрудняет понимание инструкций, поскольку это задачи, которые необходимо выполнять в определенном порядке. Вместо этого я предлагаю включить более конкретные формулировки, чтобы пользователям не приходилось прерывать процесс чтения, переключаясь между разделами или документами.
Если я заполню эти разделы до завершения стандартной временной шкалы, мне также хотелось бы очистить вопрос «Почему HPX?» (3) страница в пользовательской документации группы STE||AR. Эта страница содержит повторяющийся вводный контент, который я надеюсь объединить, а также несоответствия в написании заглавных букв (особенно в жаргоне) и голосе, которые создают ощущение разобщенности. Моей целью было бы создать более единое и последовательное введение в работу группы STE||AR.