Хотя эта идея на первый взгляд может показаться глупой, упрощенной и слишком общей, я хотел бы предложить стандартый способ документирования проектов с открытым исходным кодом. Я знаю, что каждый проект индивидуален и моя идея уже вызвала у вас улыбку, но я надеюсь вы поймёте меня, если прочитаете этот небольшой пост.
Мотивация
Нас, авторов кода, стандарт спасёт от необходимости придумывать структуру документации для очередного проекта. Намного проще заполнять пробелы в заранее подготовленной структуре, чем думать о ней каждый раз. А чем проще и быстрее это будет происходить — тем больше разработчиков будет создавать хорошую документацию. (В конце концов, у нас останется больше времени на код и архитектуру — прим. пер.)
Стандартный формат также может сделать документацию более простой для понимания, если читатель будет знаком с её структурой. Для большинства вещей дизайн является лучшим способом привлечь потребителя, и именно дизайн ему нужен. Так что желание удовлетворить всех часто приводит к тому, что никто не оказывается удовлетворён, это касается и документации. Несмотря на то, что для обучения стоит применять персональный подход, я считаю, что тщательно продуманная и организованная документация позволит охватить больший процент потенциальных пользователей. Попытка же удовлетворить желания всех приводит к чрезмерному документированию: подобную документацию трудно сопровождать и она отпугивает читателя.
Во всяком случае, это только первый черновик стандарта, который я предлагаю. Комментарии приветствуются!
Стандарт (первый черновик)
Документация должна быть разбита на пять частей. Эти части не обязательно должны находится на одной странице, более того, наиболее практично располагать их на нескольких сайтах (например, автоматически сгенерированная справка по API, «официальная» домашняя страница, видео-учебник и т.д.). Тем не менее, каждый раздел должен содержать ссылки на любой другой раздел, для улучшения понимания и упрощения доступа к разным частям документации.
Порядок следования частей должен быть регламентирован. Две из предлагаемых мной частей (IV и V) не требуют чёткого порядка, но в целом для новичка он должен быть очевиден. Никто не должен тратить время на то, чтобы понять как следует читать документацию.
В следующих разделах я буду часто писать так, как будто я не автор документации, а её читатель. Я специально делаю это, чтобы вы поняли мою точку зрения. Обычно трудно думать о документации своего проекта, поэтому предлагаю вам при чтении вспоминать примеры документации, которую вам самим приходилось изучать. Мне кажется очевидным, что документация должна быть разработана на основе того, что полезно для читателя, а не исходя из простоты её написания.
Обратите внимание, что на данном этапе я не предлагаю формального названия разделов, и я не уверен, действительно ли конкретные названия должны быть частью стандарта.
I. Что это и чем это может вам пригодиться
Это очень важная часть, которую обычно забывают. Часто мы обращаем наше внимание на ПО потому что где-то слышали название, оно показалось нам интересным и мы хотим понять, будет ли оно нам полезно. Мы можем не знать:
- какие задачи оно решает
- как заставить его работать (окружение, зависимости)
- его недостатки
- для чего оно точно не предназначено
- как оно соотносятся с аналогами
Вся эта информация чрезвычайно полезна, и это, пожалуй, самая трудная часть документации, которую должен написать разработчик. Как авторы, мы хорошо знаем, что делает наш код. По этой причине хорошо бы написать эту часть документации в начале развития вашего проекта, в идеале еще до его начала. Конечно, вы будете изменять её в процессе того, как будете реализовывать или добавлять новый функционал. Возможно, вы даже измените свои цели и приоритеты. Но важно, чтобы вы заложить основу этой части документации в тот момент, когда сами являетесь новичком для вашего проекта. Как только вы будете знать подробности, вам будет трудно абстрагировать от них.
II. Как это скачать/купить, установить и настроить
В случае свободного ПО с открытым исходным кодом, URL для загрузки часто располагается в непосредственной близости от документации, но никто не знает, не изменятся ли они в будущем. Так что сделайте вид, будто пишете старую добрую бумажную книгу без гиперссылок. Расскажите своим читателям:
- как получить ПО (URL для скачивания, команды для установки с помощью менеджера пакетов)
- как его установить (или необходимо указать список поддерживаемых платформ)
- каковы основные конфигурационные опции
- как убедиться в том, что ПО установилось и работает корректно
- основные проблемы, которые могут возникнуть во время установки
III. Как начать это использовать (учебник)
После того, как ПО будет установлен, вы захотите начать его использовать, сделать что-то простое чтобы получить представление о нём, его философии и доступном интерфейсе. Возможно, это будет не совсем то, что вам нужно, но если вы сможете сделать что-нибудь простое за пять-десять минут, вы почувствуете себя уверенно. Сделать так, чтобы у ваших читателей это получилось.
IV. Как сделать более сложные вещи (тематические руководства)
Три приведённые выше части часто находятся в README файле репозитория или архива с исходным кодом. Это первая часть, которая, вероятно, будет находиться в другом месте, так как она может быть достаточно большая, чтобы прочитать её последовательно за один раз. Для этого она должна быть хорошо проиндексирована (как минимум содержать оглавление) и содержать в себе отдельные руководства, расположенные в порядке увеличения сложности. Трудно придумать абстрактные интересные примеры, так что начните с описания того, как вы сами используете свой продукт, или того, как бы вы хотели его использовать. Если вас спросят «Как сделать ___?», добавьте ответ на вопрос в эту часть документации.
V. Справка по API (сгенерированная автоматически)
Наконец, хорошую справка по API очень важна для крупных проектов. Если вы пишете плагин для RoR, который содержит два метода, то такая справка, вероятно, не нужна. Тем не менее, ваш код должен всегда быть хорошо прокомментирован и при написании документации следует вернуться к коду привести в порядок комментарии в нём. Если вы пишите код также, как это делаю я, вы будете неприятно удивлены, насколько не информативны бывают описания ваших методов.
Ваше во время написания кода должно сильно отличаться от того, как вы мыслите во время написания документации. Как правило, вы должны обнаружить, что ваши комментарии в коде слишком специфичны, что вы считаете очевидными многие вещи, которые следуют только из контекста, в котором будет вызван метод. Это происходит потому, что когда вы пишете код метода, вы погружены в решение какой-то конкретной задачи, забывая о других примерах использования. Такое необходимо для написания кода и бесполезно для объяснения его смысла.
Короче говоря, когда вы не пишете код, возвращайтесь к уже написанному и дописывайте подробности в комментарии к вашим методам, чтобы был понятен смысл всех параметров.
Вопросы, проблемы и идеи
Я сказал это уже несколько раз, но я думаю что стоит повторить еще раз: очень трудно объяснить свой собственный код. Очевидным решением этой проблемы является просьба написать документацию кому-нибудь другому. Чего бы я хотел видеть, так это большего числа разнообразных вкладов в документацию проектов с открытым исходным кодом. Первое чтение документации проекта имеет решающее значение для нового пользователя. Они находятся в уникальном положении, так как близко не знакомы с проектом. Именно поэтому я настоятельно рекомендую, чтобы разделы I, II и III были включены в репозиторий исходного кода проекта, где они могут быть проверены и отредактированы кем угодно. Это также отличный способ воспитать в людях привычку делать вклад в проекты с открытым исходным кодом, которые они используют. Первый вклад, как правило, самый трудный, но многих английский язык пугает не так, как исходный код.
Что ещё стоит добавить о постоянно меняющихся API? Верно ли, что быстрые изменения приводят к тому, что комментарии или обсуждения являются лучшим способом для документирования проекта, чем один цельный документ? Я, наверное, потратили больше времени на чтение блогов и других неофициальных документов, чем на чтение официальной документации каждого проекта с открытым исходным кодом с которыми я работал. Однажды прочитав официальную документацию, я вряд ли вернусь к ней, чтобы узнать, что нового в ней появилось, потому что она кажется настолько статичной… Я могу перечитывать полезные разделы, о существовании которых я знаю, но только если есть некоторый показатель того, что что-то было добавлено (с какого времени? когда я последний раз читал это?). Я вряд ли буду самостоятельно искать изменения в документации. Эта проблема выходит за рамки данной статьи, но она важна, чтобы показать несовершенство этого черновика стандарта. Это может означать, что комментарии должны быть разрешены на страницах документации (в дополнение к правки), или, что нам нужно каким-то образом быстро показывать читателю, что нового добавлено (возможно, правки должны быть стилизованы под комментарии). история изменений в стиле wiki-стиле, конечно, сохранит историю изменений, но мне кажется необходимым более понятно презентовать эти изменения.
Мы также нуждаемся в способе указания даты и версии программного обеспечения в документации. Я думаю, что состояние официальной документации, как правило, настолько плохо, что мы привыкли предполагать, что прочитанное нами уже устарело. Механизм для быстрой отметки версии пункта или раздела, чтобы указать его соответствие текущей версии ПО, был бы очень полезен. (С другой стороны, пользователи могут сами пометить разделы или параграфы как устаревшие, но это не решает проблему представления степени актуальности документации для новых пользователей). Я думаю, что официальные документы часто становится устаревшей именно потому, что в ней не отображается дата её обновления.
Во всяком случае, я надеюсь, что написанного мной достаточно, чтобы убедить вас в возможности создания и пользы от стандарта документации для проектов с открытым исходным кодом. От этого выиграют как пользователи ПО, так и его авторы. Пожалуйста, оставьте ваш комментарий и дайте мне знать, что вы думаете по этому поводу.
Автор: Sannis
