Коллеги, всех приветствую.
Работая программистом Битрикс с 2010 года, сталкивался регулярно с ситуацией: что надо обязательно вести документацию проекта, особенно если работаешь в команде. (кратко перечислю зачем это нужно, но думаю все и так знают: меньше багов связанных с поломкой неочевидной бизнес логики; соблюдение единообразия развития проекта - одинаковый код, одинаковая файловая система и тд; проще оценить новые поступающие задачи,т.к.не теряется время на изучение того что уже есть; в целом проще и быстрее поддерживать и развивать сайты).
Понятно, что это делать нужно, но реально удобных инструментов так и не встречал.
Часто документацию вообще не пишут, а если пишут, то обычно в wiki на портале битрикс24, или в каком-нибудь стороннем сервисе
Оба варианта обладают рядом неудобств:
1. Надо открывать дополнительные окна для наполнения документации (помимо кучи вкладок с разрабатываемым сайтом). Программисту приходится тратить дополнительное внимание на переключение между вкладками. Теряется контекст задачи.
Кто работает программистом - тот понимает, что это не мелочь, когда работы много и она сложная. От этого устаешь и документация вместо помощи становится еще одной проблемой.
2. Часто бывало, что одна студия разрабатывала сайт и писала всю документацию в какой-нибудь сервис. Потом владелец сайта сменил веб студию, и вся документация пропала вместе с первой студии. Получить накопленную информацию о том как работает какой-нибудь раздел сайта становилось невозможно. Терялись часы на разбор бизнес логики по исходным кодам.
3. Возможности сервиса по наполнению документации обычно очень скудные:
-редактор текста
-разделение текста на папки
-возможно, прикрепление файлов к тексту
-если повезет, то сохранение измененных версий текстов
Этого не достаточно
4. Поскольку, все хранится на стороннем сервисе, то для каждого программиста надо заводить пользователя и наделять его нужными правами на доступ к докам. Бывало, что админ был не на связи в нужный момент, и программисту не выдавали права на доступ к сервису с доками сразу. Получалось, что программист выполнял работу, забывал уже, что и где делал, и спустя время его добавляли в сервис документации. Понятно, что он туда уже ничего не записывал. И документация отставала от последней версии кода на сайте.
Речь идет и про описание бизнес логики и технической документации.
5. И бывало, что документация просто хранилась в виде первоначального ТЗ у какого-то из менеджеров на компьютере. И, разумеется, в какой-то момент времени просто терялась с менеджером или без
Я решил сделать модуль для битрикса, который решил бы все эти проблемы сразу.
Закончил его делать и спешу . Хотел бы получить обратную связь от коллег: что добавить, изменить, исправить, чтобы он стал еще лучше.
Модуль документации интегрирован в интерфейс БУС, в его административную панель в публичной части сайта. Для работы с документацией теперь нужно минимум кликов.
Он имеет очень широкий функционал, который невозможно реализовать в сторонних сервисах.
Например, теперь можно, в том числе, оставлять просто Php комментарии в коде, не открываясь от работы, и они станут частью полноценной документации (будут выведены автоматически. Об этом ниже).
Кроме того теперь вся документация сайта связана между собой: можно написать описание бизнес логики большого раздела сайта, привязав текст к компонентам, файлам, модулям, классам, выбрав их из списка. После этого во-первых, при чтении документации будет автоматический вывод php комментариев из указанных сущностей. Во-вторых, если будет документация которая также привязана к какой-нибудь из этих сущностей - она автоматически будет выведена. Таким образом вся связанная информация будет изучена за один раз. Как бизнес логика , так и технические особенности из php комментариев.
Ну и одно из главных - теперь документацию можно привязать к url адресу. И когда этот адрес открыт в браузере - модуль выведет всю документацию, которая к нему привязана. Причем модуль определит какие компоненты/модули/файлы/классы вызываются на текущей странице - и если для них есть документация или внутри них есть php комментарии, то он выведет их!
В общем была идея сделать максимально удобный инструмент для разработчиков и менеджеров проектов.
Он только появился и сейчас нужна обратная связь.
Установить можно через на любой сайт на БУС. В том числе на коробочную версию битрикс24. (Там очень часто на одну страницу навешивается куча доработанной бизнес логики. И очень важно документировать все, что было сделано нестандартного. т.к. уже за пару месяцев развития там накапливаются сотни сценариев кастомных.Теперь очень удобно их можно записать в модуль, и привязать к URL. Это сэкономит время на поддержку).
находится видео обзор и инструкция
П.С. Если модуль вам понравился, то предложите его внедрить в работу в вашей студии.
Модуль может стать стандартом хранения документации на всех проектах на Битрикс.
На него действуют партнерские скидки!
Работая программистом Битрикс с 2010 года, сталкивался регулярно с ситуацией: что надо обязательно вести документацию проекта, особенно если работаешь в команде. (кратко перечислю зачем это нужно, но думаю все и так знают: меньше багов связанных с поломкой неочевидной бизнес логики; соблюдение единообразия развития проекта - одинаковый код, одинаковая файловая система и тд; проще оценить новые поступающие задачи,т.к.не теряется время на изучение того что уже есть; в целом проще и быстрее поддерживать и развивать сайты).
Понятно, что это делать нужно, но реально удобных инструментов так и не встречал.
Часто документацию вообще не пишут, а если пишут, то обычно в wiki на портале битрикс24, или в каком-нибудь стороннем сервисе
Оба варианта обладают рядом неудобств:
1. Надо открывать дополнительные окна для наполнения документации (помимо кучи вкладок с разрабатываемым сайтом). Программисту приходится тратить дополнительное внимание на переключение между вкладками. Теряется контекст задачи.
Кто работает программистом - тот понимает, что это не мелочь, когда работы много и она сложная. От этого устаешь и документация вместо помощи становится еще одной проблемой.
2. Часто бывало, что одна студия разрабатывала сайт и писала всю документацию в какой-нибудь сервис. Потом владелец сайта сменил веб студию, и вся документация пропала вместе с первой студии. Получить накопленную информацию о том как работает какой-нибудь раздел сайта становилось невозможно. Терялись часы на разбор бизнес логики по исходным кодам.
3. Возможности сервиса по наполнению документации обычно очень скудные:
-редактор текста
-разделение текста на папки
-возможно, прикрепление файлов к тексту
-если повезет, то сохранение измененных версий текстов
Этого не достаточно
4. Поскольку, все хранится на стороннем сервисе, то для каждого программиста надо заводить пользователя и наделять его нужными правами на доступ к докам. Бывало, что админ был не на связи в нужный момент, и программисту не выдавали права на доступ к сервису с доками сразу. Получалось, что программист выполнял работу, забывал уже, что и где делал, и спустя время его добавляли в сервис документации. Понятно, что он туда уже ничего не записывал. И документация отставала от последней версии кода на сайте.
Речь идет и про описание бизнес логики и технической документации.
5. И бывало, что документация просто хранилась в виде первоначального ТЗ у какого-то из менеджеров на компьютере. И, разумеется, в какой-то момент времени просто терялась с менеджером или без
Я решил сделать модуль для битрикса, который решил бы все эти проблемы сразу.
Закончил его делать и спешу . Хотел бы получить обратную связь от коллег: что добавить, изменить, исправить, чтобы он стал еще лучше.
Модуль документации интегрирован в интерфейс БУС, в его административную панель в публичной части сайта. Для работы с документацией теперь нужно минимум кликов.
Он имеет очень широкий функционал, который невозможно реализовать в сторонних сервисах.
Например, теперь можно, в том числе, оставлять просто Php комментарии в коде, не открываясь от работы, и они станут частью полноценной документации (будут выведены автоматически. Об этом ниже).
Кроме того теперь вся документация сайта связана между собой: можно написать описание бизнес логики большого раздела сайта, привязав текст к компонентам, файлам, модулям, классам, выбрав их из списка. После этого во-первых, при чтении документации будет автоматический вывод php комментариев из указанных сущностей. Во-вторых, если будет документация которая также привязана к какой-нибудь из этих сущностей - она автоматически будет выведена. Таким образом вся связанная информация будет изучена за один раз. Как бизнес логика , так и технические особенности из php комментариев.
Ну и одно из главных - теперь документацию можно привязать к url адресу. И когда этот адрес открыт в браузере - модуль выведет всю документацию, которая к нему привязана. Причем модуль определит какие компоненты/модули/файлы/классы вызываются на текущей странице - и если для них есть документация или внутри них есть php комментарии, то он выведет их!
В общем была идея сделать максимально удобный инструмент для разработчиков и менеджеров проектов.
Он только появился и сейчас нужна обратная связь.
Установить можно через на любой сайт на БУС. В том числе на коробочную версию битрикс24. (Там очень часто на одну страницу навешивается куча доработанной бизнес логики. И очень важно документировать все, что было сделано нестандартного. т.к. уже за пару месяцев развития там накапливаются сотни сценариев кастомных.Теперь очень удобно их можно записать в модуль, и привязать к URL. Это сэкономит время на поддержку).
находится видео обзор и инструкция
П.С. Если модуль вам понравился, то предложите его внедрить в работу в вашей студии.
Модуль может стать стандартом хранения документации на всех проектах на Битрикс.
На него действуют партнерские скидки!