На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- SciPy
- Технический писатель:
- мкг33
- Название проекта:
- Ориентированная на пользователя документация и тщательная реструктуризация
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание Проекта
Мотивация:
Я намерен заняться рефакторингом существующей документации, чтобы она была легко доступна пользователям с разными потребностями. Само собой разумеется, что исследователя, скорее всего, интересуют расширенные и тонкие функции, тогда как пользователь без предварительного опыта оценит пошаговые руководства и диаграммы.
Я заинтересован в продолжении этого проекта по личным и профессиональным причинам: во-первых, я хотел бы внести существенный вклад в SciPy, потому что мои собственные исследования получили от этого большую пользу, а во-вторых, я слишком часто сталкиваюсь с недостаточной (или отсутствующей) документацией в других программного обеспечения и всегда задаемся вопросом, насколько быстрее (если все это!) пользователи могли бы научиться использовать код, если бы им было предоставлено подробное руководство.
Цели:
Я стремлюсь улучшить существующую документацию SciPy как по содержанию, так и по графике. Наиболее важной особенностью моего подхода к этой проблеме является проведение и анализ опроса пользователей, то есть краткого опроса, проводимого онлайн, позволяющего различным пользователям озвучить свои потребности относительно документации. Я твердо убежден, что их мнения должны быть источником вдохновения (как еще мы можем создать более удобную для пользователя документацию?).
Что касается реализации самого проекта, первый этап будет включать разработку и анализ опроса пользователей, а также решение нескольких стилистических проблем, которые я заметил в текущей документации. Например, отсутствие последовательности (пример: двумерные массивы встречаются рядом с двумерными массивами), запутанные предложения, которые необходимо переписывать, или отсутствие алфавитного порядка на определенных подстраницах. Второй этап будет посвящен внедрению графических руководств, содержащих гиперссылки на соответствующие темы (на основе результатов опроса и других запросов сообщества). В конечном итоге я хочу получить удовлетворительную документацию, адаптированную для разных типов пользователей. Более того, я постараюсь сделать учебные пособия более единообразными как лингвистически, так и структурно. И последнее, но не менее важное: я стремлюсь написать новые руководства (исходя из текущих потребностей сообщества).
Опрос пользователей:
Что касается опроса пользователей, я предлагаю использовать Google Forms по нескольким причинам. Прежде всего, Google Forms бесплатны и предлагают неограниченный функционал (по количеству респондентов, вопросов и т. д.), имеют привлекательную визуальную форму, максимально полезные опции опроса (например, настраиваемый линейный масштаб, флажки и множественный выбор), и, что самое главное, результаты можно легко экспортировать для целей статистического анализа. Судя по онлайн-исследованиям, Google Forms, по крайней мере на данный момент, является лучшим бесплатным инструментом для проведения опросов. Если говорить менее серьёзно, то было бы неплохо использовать продукт Google в рамках инициативы Google.
Я создал предварительный опрос с примерами вопросов (доступен по адресу https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform ). Разумное количество вопросов в окончательной версии должно составлять от десяти до пятнадцати. Чтобы получить конкретные результаты, я предлагаю преимущественно использовать вопросы с несколькими вариантами ответов, линейную шкалу и несколько флажков. Однако линейная шкала не должна напоминать полный спектр (это только вызывает путаницу, и результаты, вероятно, будут страдать от высокой дисперсии). Должно быть максимум два открытых вопроса, иначе результаты будут сильно разрозненными и совершенно бесполезными. Я считаю, что даже очень большое количество ответов не будет проблемой, поскольку данные можно легко экспортировать и автоматически анализировать с помощью статистического программного обеспечения. Если предположить, что количество ответов действительно очень велико, анализ открытых вопросов может занять некоторое время, но я предполагаю, что он не будет утомительным. В конце концов, среднестатистический пользователь вряд ли напишет эссе о состоянии документации. В худшем случае некоторые ответы можно просто сохранить для будущего анализа.
Графические руководства:
Мое видение графических руководств (предназначенных для использования в качестве инструментов навигации) основано на популярном предположении, что (большинство) людей лучше обрабатывают простые визуальные структуры, а не чисто текстовую информацию. Более того, тематически ориентированная диаграмма с линиями, соединяющими схожие интересующие темы, несомненно, является очень ценным активом для менее опытных пользователей (и не только).
Что касается деталей реализации, предлагаю использовать пакет TikZ. Прежде всего, это мощный инструмент, и, похоже, он не скоро устареет. Он также предлагает высококачественный вывод, имеет действительно надежную документацию и является частой темой на TeX StackExchange и других основных форумах. Самое главное, что интеграция файла TikZ (точнее, многочисленных гиперссылок в нем) с HTML-документацией не представляет существенных проблем благодаря существованию различных пакетов и исправлений для встраивания изображения TikZ в HTML (например, TeX4ht). .
Вопрос дальнейшего обслуживания руководств в SciPy можно легко решить, используя, скажем, Overleaf (облегчает совместную работу и предлагает мгновенный предварительный просмотр) и предопределенные шаблоны, которые я предоставлю. По сути, графические руководства вряд ли будут сильно отличаться друг от друга. Структура, цветовая палитра и формы более или менее будут инвариантными, поэтому последующее изменение формы и дальнейшая настройка не будет проблемой.
(Пожалуйста, ознакомьтесь с полной версией предложения, доступной в общей папке GSoD.)