×Закрыть

Как делать документацию/визуализацию сайтов со сложной структурой?

Что происходит?
Развиваем сложный сайт на котором огромное количество страниц и взаимосвязанного функционала .

В чем проблема?
Когда меняется программист то ему сложно вникнуть в проект и понять что с чем связано логически. В итоге меняя функционал в одном месте, он не видит что этот функционал использовался в другом.

Аналогичная проблема при проектировании обновлений сайта. Часто меняя функционал в одно месте, ломаем что-то в другом.

В чем вопрос?
Хотелось бы понять как ведут техническую документацию на крупных проектах или крупных компаниях-разработчиках?

Как облегчить знакомство со сложным сайтом для нового разработчика?

Есть ли какие-то варианты визуальной карты сайта для разработчиков, где показано какой функционал на что влияет на сайте и с чем связан.

LinkedIn
Допустимые теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter
Допустимые теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter

Хотел написать: пиши тесты
Но ниже уже написали

Трохи дивують ці протилежні речі:

огромное количество страниц и взаимосвязанного функционала
Когда меняется программист то ему сложно вникнуть в проект и понять что с чем связано логически.

Тобто зв’язок або є, або його немає. Теоретично увесь логічний зв’язок можна прочитати в коді. Бо код і є та логіка.

Переконаний, що основна документація для програміста — це мова програмування. Бо мова програмування — це мова. Код — це мова. І так далі за логікою ...

А давайте поговоримо на цю тему:

меняя функционал в одном месте, он не видит что этот функционал использовался в другом
меняя функционал в одно месте, ломаем что-то в другом

Для вирішення усіх подібних проблем потрібно розглянути детально хоча б кілька з них.

Наприклад:
Завдання: Змінити кількість статей на сторінці /a.мргт з 10 на 20.
Дія: Програміст знайшов цифру, яка вказує кількість для цієї сторінки і змінив.
Наслідок: Зміна вплинула не лише на сторінку /а.мргт але й на /б.мргт та /в.мргт.
Проблема: Змінити потрібно було кількість лише на одній сторінці замість трьох.

Чи є можливість у програміста передбачити без документації, що внесення зміни вплине на три сторінки замість однієї? В даному випадку — так. Який ваш випадок?
Чи передбачає завдання, що зміна повинна бути лише на вказаній сторінці без підтексту зміни на залежних сторінках? Тут залежить від методу спілкування. Зазвичай хочуть, щоб розуміли з пів слова. Тобто чи може подібний підтекст з’явитися через замале «пів слова» в завданні? Думаю, що це просто закономірно.
Чи міг постановник завдання передбачити підтекст? Можливо й так, можливо й ні.
Чи повинен був програміст дослідити вплив зміни та відповідність цієї зміни завданню? Так.
Чи повинен був програміст зрозуміти підтекст? Зобов’язаний уточнити деталі, якщо є підозри щодо невідповідності або неточності результатів зміни до тексту завдання. Теоретично підозри у ваших випадках не з’являються щодо невідповідності. Чи допоможе документація в подібних випадках?

ломаем что-то в другом

Тут теж можна багато здогадок намалювати.

Є підозра, що у вашому випадку описані проблеми можна буде вирішити саме через покращення якості коду та через покращення деталізації завдань, а не завдяки додатковій документації.

Але для подібних висновків замало інформації.
Раджу також розглянути і вище описаний варіант.

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

Здесь конечно играет роль как правильно проектировщик пишет ТЗ, но он тоже не может держать всю логику в голове, тк она (логика) огромная, ее всю не запомнить.

Поэтому важно где-то вести документацию.

В этом и был вопрос, как ее ведут для крупных и сложных проектов.

Це не приклади. Це загальні фрази. Успіхів вам в цьому.

Судя по описанию и примеру ниже, у Вас проблема не с документацией а с кодом.

с ангуларом, наверное ...

все просто — пиши нормальные тесты, а не те, которые нынче пишет большинство, и все будет нормально.

Нужно делать так, как нужно. А так как не нужно — делать не нужно
©Винни-Пух aka в-голове-моей-опилки

Ну как бы кроме нормальных тестов автору не поможет, это как бы главная цель тестов — гарантировать безопасность изменений

Ты прям совсем уж бюрократ: Что бы ни менялось, лишь бы ничего не менялось.

как раз ни разу не бюрократ. это идти в документацию — заниматься бюрократий. а это решение проблемы

Документация всегда рассматриваю двух видов. Первая — документация функционала, которую пишет БА, и по которой любой БА сможет вникнуть в логику самого функционала. Вторая — документация девелопера для разработки.
Каждый ее пишет как умеет/научился.
Для меня наиболее приятно MS Visio или XMind + обычный вордовский файл, который при написании должен быть четко структурирован. Как правило, на написание первой четкой документации по проекту/подсистеме нужно 3-4 итерации. Сначала пишешь первый релиз, потом берешь паузу в несколько дней, потом возвращаешься к нему и правишь/добавляешь/структурируешь. Человек, который такое пишет должен обязательно уметь систематизировать информацию, иначе получается каша, которую потом никто не прочитает.
Тест на «нормальность» документации очень простой: после ее написания даете какую-нибудь сложную ее часть двум-трем БА или девелоперам (в зависимости от вида документации (см. вначале)), которых считаете наиболее опытными/системно мыслящими. Если человек за 2-3 часа может вникнуть в пусть даже небольшой кусочек сложного функционала — значит документация написана нормально.

Спасибо большое, пока что это лучший ответ! Именно об этом я и задавал вопрос.

Если можете подробнее рассказать (или показать примеры или отправить куда-то почитать) о документации для разработчика — буду благодарен. Хочется понимать как это делать на качественном уровне, а не тяп-ляп.

П.С. под «документация разработчика» имею в виду не ТЗ или список задач (старых/текущих/новых) а именно документацию по проекту, читая которую любой новый разработчик поймет как всё устроено с точки зрения кода и не будет делая изменения в одном функционале, случайно ломать другой.

Сейчас популярен подход «docs as code».
Дока по разрабатываемому компоненту хранится в репозитории этого компонента, а общая дока по продукту собирается принимая в качестве вводных данных те файлы, что хранятся в репах компонентов.
Исходные файлы доки пишут на языке разметки (Markdown, Asciidoc, etc.), чтобы потом скормить док-генератору (их огромное количество на любой вкус).
Настраивают CI/CD так, чтобы генератор автоматически собирал эту доку и публиковал ее где нужно. Можно периодически, можно по действию (коммит в мастер и пр.).
Есть еще test-driven documentation (используется для документации API) — это когда дока собирается в результате прохождения тестов.

Этот подход ещё старина Авгий практиковал. Легенда говорит, что его убили в результате менеджмента проекта.

Ничего не делайте, просто продолжайте работать. Большое количество разрывов логики и недоделок — признак быстро развивающегося проекта. Ставьте метки TODO и раз в неделю (или сколько там у вас спринт) делайте ревизию этих меток просто чтобы удостовериться, что вы ничего не забыли. Если есть уходящий, назначьте кого-то кто будет владеть его метками и решать что-то с ними. Если это решается долго — пишите что как и почему прямо в комменты к этому TODO, сколько б места они не занимали, или отдельный текстовый файл с логом обсуждения (и ссылка на него).

Почему так: какой-то очень небольшой процент этих меток может зависнуть надолго. Распределение экспоненциально. Но даже 1...3 таких забытых меток хватит чтобы отравить проект и сильно испортить впечатление у его пользователей. Представьте себе сколько их забытых, когда вы вообще не метите.

Выгода такого решения — дёшево. Промежуточный этап перед выносом неочевидных задач в бэклог. Позволит после написания 90% кода адекватно оценивать оставшиеся 90% :)

У грамотно составленного лога TODO, равно как и у бэклога, есть свойство быстрого разрешения. То есть не стоит смотреть на его размер и бояться, наоборот, чем лучше он описан и задокументированны разрывы, тем быстрее принимается по ним решение и тем проще они закрываются. Обычная подготовка к релизу. И вы удивитесь, что так избавились от овертаймов.

спасибо за ответ, но вопросы был не в том как программисту делать текущие задачи, а в том как сделать так чтобы любой новый разработчик/проектировщик мог быстро вникнуть в проект, понять что и как работает и с чем связано.

Например простая задача — поменять что-то в работе с валютами. Но эти валюты используются в кабинете владельца компании, на фронтэнде, тарифах и еще нескольких местах.

Сейчас всё это держится в голове проектировщика, но то проект растет очень сильно то нужно всё это как-то записать или визуализировать. В этом и был вопрос: как это делают в крупных проектах или компаниях?

Не поверите — ведут документацию :)

Обожаю «остроумные» ответы :)

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

Если ведут что-то еще визуальное (в виде каких-то схем и т.д.), то тоже через какой сервис?

Это уже у ваших разработчиков спросите как им удобнее

очевидно же, что большинству удобнее (читай — лень) — не вести документацию

Тогда пусть ведут ее в коде, а оттуда можно генерить

Да хоть бы и на доске с маркером и липкими листочками. 100500 проверенных средств. Я к примеру канбаны люблю за их компактность хранения и лёгкость остановки любой задачи — особенно когда кто-то решил чутка повременить с оплатой.

как удобно — так и ведут. если есть кто то, кто умеет в «скрипты», то можно парсить код что бы составить «карту вхождений» (где какие имена используются), на основании выявленных списков — прописывается база определений (что это и зачем, как правило это определение должно быть в коде закомменчено, такое и называется «документировать», но если с комментами в коде — беда, то это как раз возможность «начать» ). И так далее... по факту нужен «творческий подход»
— адаптация неких методик документирования к тому что вами реально будет использоваться.

А кто вам таки сказал, что это «быстро» существует. В шутке про «быстро — качественно — недорого» только доля шутки. По мере разделения труда стоимость растёт ой-как не линейно.

Как делают я объяснил — есть понятие «бэклог», он же технический долг. И если проект начинает рваться, никакая голова проектировщика его не удержит, даже когда пишет 1 человек. Когда я сам пишу — я вынужден растить день вплоть до 16 часов чтобы удержать в голове то что пишу и уйти от лишнего документирования, но как только видится какой-то разрыв по дням — ОБЯЗАТЕЛЬНО этот бэклог формируется.

Разница между TODO и бэклогом проекта элементарна: TODO пишется для себя, особенно для очень несрочных задач, но которые собирался делать сам. Типично — написать или улучшить тесты. Никто за тебя их не напишет кроме случаев форс-мажора. Бэклог пишется уже в проект и так чтобы всем понятно было или как минимум менеджеру.

И вот как раз с бэклогом манагеру ничего объяснять не надо — если конечно он PM, а не просто дядя в галстуке. А вот с кучей мелких TODO — далеко не всем кодерам очевидно, что свои авгиевы конюшни тоже нуждаются в менеджменте, что никогда не знаешь, на что более срочное тебя прервут или на каком геморое застрянешь и вынужден будешь уйти в RTFM.

Подписаться на комментарии