Почему нужна собственная документация

При разработке собственных решений, а также созданию проектов на Bitrix Framework с интеграцией с различными сервисами, с нестандартным специфическим функционалом крайне рекомендуется ведение собственной документации. И чем нетипичнее, крупнее, длительнее, сложнее и объёмнее проект, чем больше исполнителей над ним работает, тем более необходима документация и более обширной и разноплановой должна она быть.

Какие проблемы решает собственная документация:

1. Трудности с подключением нового разработчика. Требуется довольно много времени на то, чтобы ему разобраться с уже реализованным функционалом.
2. Трудности с донесением изменений по архитектурной и функциональной части до других разработчиков.
3. Иногда могут возникать ошибки из-за использования устаревших функций, написанных другим разработчиком, но при беглом взгляде другого вроде решающих его задачу и так далее.
4. Сложности при планировании новых функциональных блоков.
5. Проблемы с поддержкой собственных решений в Маркетплейс.

Проблема комплексная, так как требует не только документирования исходного кода, но и написания документации для администраторов и пользователей. Другими словами, требуется сделать всё то, что делает вендор.

  Пользовательская и администраторская документация

Самое простое в этом комплексе - это создание администраторской и пользовательской документации. Причём с администраторской документацией всё может быть ещё проще, так как есть штатная возможность системы использовать подсказки к полям компонентов.

Считается, что пользовательская документация требуется не всегда, но это не так. Нужно исходить из того, что работать с вашим проектом будут не только квалифицированные или, хотя бы, пытливые люди, но и безразличные ко всему неумёхи, которым надо всё показывать "от и до". Ну, а в больших проектах с "навороченным" нештатным функционалом от неё вообще никуда не деться.

Создание такой документации не представляется сложным этапом в работе. Её в состоянии выполнять сотрудники с уровнем "продвинутого пользователя". Здесь больше вопрос ресурсов, оплаты их труда, многие студии пренебрегают этим этапом.

  Документация для разработчиков

Сложность создания документации для разработчиков имеет объективные и субъективные основания. Объективные:

• Писать её, кроме самого разработчика, некому. Сторонний неквалифицированный сотрудник не сможет детально разобраться в коде. Держать отдельно квалифицированного программиста на написании документации по чужому коду - даже не роскошь, а глупость.
• Функционал никогда не выходит не то что в неизменном, а даже в законченном виде. Поэтому написание документации, как правило откладывается "на потом" и успешно забывается.
• Неверная организация процесса разработки не оставляет времени на написание документации. При сжатых сроках и несоответствующем бюджете разработчик стремится снизить свои трудозатраты.

Субъективная причина одна: психологическое неприятие разработчиком необходимости писать документацию.

Объективные трудности должны преодолеваться за счёт правильной организации процесса разработки. Субъективные - за счёт постоянной разъяснительной работы, терпеливого убеждения.

При разработке своих классов и функций разработчик должен их документировать в формате PHPdoc или сходном диалекте. Это позволяет:

• осуществить показ человеческих подсказок по коду на уровне IDE;
• иметь возможность посмотреть описание чужого класса и быстро с ним разобраться;
• иметь возможность генерации списков todo на следующую итерацию или для себя.

В качестве инструментов можно использовать:

• doxygen
• PHPDocumentor
• phpdoctor

При использовании любого инструмента придётся разбираться с кодировками. Это особенность, связанная с Bitrix Framework: при выставленном в настройках проекта UTF-8, в коде ядра портятся комментарии.