Существует ряд причин, по которым любому проекту необходима превосходная документация. Вот несколько из них:
- Адаптация новых участников: Четкая документация помогает новым разработчикам быстро понять структуру проекта, процесс настройки и правила участия.
- Внедрение пользователей: Хорошо документированные проекты с большей вероятностью будут использоваться и рекомендоваться другими, так как пользователи могут легко понять, как внедрить и использовать программное обеспечение.
- Обслуживание: Хорошая документация облегчает сопровождающим понимание кодовой базы, исправление ошибок и добавление новых функций, даже если они не писали оригинальный код.
- Сотрудничество: Она способствует лучшему взаимодействию между участниками, обеспечивая общее понимание архитектуры и процессов проекта.
- Снижение нагрузки на поддержку: Всесторонняя документация может ответить на многие общие вопросы, уменьшая необходимость прямой поддержки от сопровождающих.
- Долговечность: Проекты с хорошей документацией с большей вероятностью выживут, даже если ключевые участники уйдут, так как знания сохраняются и доступны.
- Качество кода: Написание документации часто приводит к улучшению качества кода, так как заставляет разработчиков продумывать и объяснять свои проектные решения.
- Построение сообщества: Это поощряет здоровое сообщество, делая проект более доступным и способствуя культуре обмена знаниями.
- Доверие: Хорошо документированные проекты часто воспринимаются как более профессиональные и надежные, что может быть критически важно для внедрения открытого исходного кода в корпоративных средах.
Видение документации Bastyon заключается в создании четкого, доступного и всеобъемлющего ресурса, который позволяет пользователям эффективно использовать платформу и дает возможность разработчикам создавать инновационные приложения на ее основе. Документация будет служить центральным хабом знаний, способствуя внедрению, поощряя вовлечение сообщества и поддерживая рост проекта.
Хотя они не предназначены быть предписывающими, принципы дизайна могут помочь определить подход Bastyon к стратегии выполнения.
- Модульность: Организация содержания в логические, самодостаточные модули для легкой навигации и обновления.
- Прогрессивное раскрытие: Представление информации слоями, от базовой до продвинутой, позволяя пользователям углубляться по мере необходимости.
- Согласованность: Поддержание единой терминологии, форматирования и структуры во всей документации.
- Доступность: Обеспечение доступности документации для пользователей с различными потребностями и происхождением.
- Поисковая способность: Внедрение надежной функциональности поиска с релевантными метаданными и тегами.
- Версионность: Четкое указание версий документации и сохранение архивов предыдущих версий.
- Интерактивные элементы: Включение интерактивных примеров, фрагментов кода и учебных пособий, где это уместно.
- Визуальные средства: Использование диаграмм, блок-схем и скриншотов для иллюстрации сложных концепций.
- Обслуживаемость: Человеку не должно требоваться знание markdown или github для подачи вопроса по документации.
- Общая ответственность: Ответственность каждого убедиться, что документация обновляется при функциональных изменениях или изменениях API проекта.
Как было отмечено в разделе Мотивация выше, существуют три различные персоны, связанные с документацией проекта, каждая из которых имеет свой набор задач для выполнения.
-
Новый разработчик
- Как новый разработчик, желающий внести вклад в миссию Bastyon, я могу легко найти документацию для разработчиков, чтобы начать работу с Bastyon в кратчайшие сроки.
- Как новый разработчик, желающий внести вклад в миссию Bastyon, я могу легко найти способ связаться с владельцами кода, чтобы начать работу с Bastyon в кратчайшие сроки.
- Как новый разработчик, я могу легко подать отчет о проблемах с документацией Bastyon, которые я нахожу, чтобы не тратить на это слишком много времени.
-
Текущий разработчик Bastyon
- Как текущий разработчик Bastyon, я могу поддерживать высокий уровень документации, чтобы проект был более доступным и способствовал культуре обмена знаниями.
- Как текущий разработчик Bastyon, я могу легко подать отчет о проблемах с документацией Bastyon, которые я нахожу, чтобы не тратить на это слишком много времени.
-
Пользователь
- Как новый пользователь, я могу использовать документацию для легкого ознакомления с Bastyon, чтобы мой опыт был гладким и приятным.
- Как пользователь, я могу легко подать отчет о проблемах с документацией Bastyon, которые я нахожу, чтобы чувствовать, что я вношу вклад в проект без необходимости изучать тонкости языка markdown или внутреннее устройство github.
- Как новый пользователь, я могу использовать документацию для легкого ознакомления с основными каналами "как сделать" на Bastyon, чтобы мой опыт был гладким и приятным.
-
Энтузиаст проекта (не разработчик)
- Как профессиональный переводчик, желающий внести вклад в миссию Bastyon, я хочу иметь возможность найти необходимые ресурсы для перевода материалов документации или материалов проекта на другой язык.
-
Кто-то, кто строит бизнес на использовании Bastyon
- Как новый узловой оператор, я могу использовать документацию для легкого ознакомления с Bastyon, чтобы мой опыт был гладким и приятным.
- Как новый автор, я могу использовать документацию для легкого ознакомления с Bastyon, чтобы мой опыт был гладким и приятным.
Таким образом, существует несколько функциональных требований, которые должны быть выполнены документацией Bastyon.
- Использовать подход "документация как код": Относиться к документации как к коду, используя контроль версий и инструменты для совместной работы.
- Внедрить автоматизированное тестирование: Использовать инструменты для проверки неработающих ссылок, проблем форматирования и согласованности.
- Создать цикл обратной связи: Включить механизмы обратной связи от пользователей непосредственно в документацию.
- Создать механизмы перевода: Создать процессы для отслеживания и внедрения переводов на разные языки.
- Использовать вклад сообщества: Установить четкие руководства для членов сообщества по внесению вклада в документацию.
- Интегрировать с продуктом: Встроить соответствующую документацию непосредственно в платформу Bastyon для легкого доступа.
- Внедрить аналитику: Использовать аналитику для отслеживания использования документации и выявления областей для улучшения, предполагая, что мы можем сделать это без деанонимизации пользователей Bastyon.
Учитывая, что документация уже существует, мы не начинаем с нуля, а продолжаем ее с необходимыми изменениями. Ниже приведена предлагаемая структура документации, учитывающая то, что у Bastyon уже есть.
-
Начало работы
- Обзор платформы
- Краткое руководство по началу работы
- Как оставить отзыв о Bastyon
- Часто задаваемые вопросы
-
Сообщество и поддержка
- Правила сообщества
- Каналы поддержки
- Запросы функций и сообщения об ошибках
-
Руководство по участию
- Как внести свой вклад в Bastyon
- Кодекс поведения
- Рабочий процесс разработки
-
Руководство пользователя
- Настройка и управление аккаунтом
- Использование функций социальной платформы
- Функциональность мессенджера
- Авторство на Bastyon
- Учебные пособия и руководства по использованию
- Устранение неполадок
-
Архитектура и дизайн
- Системная архитектура
- Интеграция децентрализации и блокчейна
- Функции безопасности
-
Документация для разработчиков
- Справочник по API
- Документация по SDK
- Руководство по разработке мини-приложений
- Лучшие практики и примеры
- Учебные пособия
Документация не является самоцелью, а скорее постоянным процессом уточнения того, что сообщается участникам проекта или пользователям. Тем не менее, существует последовательность выполнения, которой мы можем следовать для создания надежных процессов.
-
Оценка и планирование
- Аудит существующей документации
- Определение ключевых заинтересованных сторон и их потребностей
- Создание канала документации и приглашение заинтересованных сторон
- Сообщение ключевым заинтересованным сторонам об ожиданиях и предлагаемых изменениях
- Получение согласия от заинтересованных сторон
- Определение целей и метрик документации
-
Настройка инфраструктуры
- Выбор новой платформы для документации (например, GitBook, ReadTheDocs, MediaWiki и т.д.), поддерживающей обратную связь от пользователей, или использование существующей.
- Выбор других инструментов (нам нужно что-то для перевода, сканера мертвых ссылок и т.д.)
- Настройка интеграции контроля версий с обратной связью.
- Установление рабочего процесса для внесения вклада
- Внедрение принципа "вы вносите изменение, вы документируете обновление" для сообщества разработчиков.
-
Создание контента
- Разработка руководства по стилю
- Создание шаблонов для различных типов документов
- Начало написания/обновления основных разделов документации
-
Обзор и итерация
- Внедрение процесса экспертной оценки
- Сбор обратной связи от пользователей
- Непрерывное улучшение и обновление контента
-
Запуск и продвижение
- Продвижение документации через различные каналы
-
Обслуживание и расширение
- Регулярные аудиты контента и обновления. Можем ли мы использовать какие-то инструменты для выявления мертвых ссылок и т.д.?
- Расширение документации на основе потребностей пользователей и роста платформы
- Создать онлайн сообщества, обсуждаюшие доментацию
- Обучение участников сообщества
Следуя этой стратегии документации, Bastyon может создать надежный, удобный для пользователя и всеобъемлющий ресурс, который поддерживает как пользователей, так и разработчиков. Этот подход поможет стимулировать внедрение, снизить нагрузку на поддержку и способствовать процветающей экосистеме вокруг платформы.
https://app.archbee.com/signin
https://github.com/readthedocs/readthedocs.org/tree/2f48c81e9ce162bbd34229e897db84044b00fe31