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

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

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

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

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

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

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

👍ПодобаєтьсяСподобалось0
До обраногоВ обраному0
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

Надо бы для своего движка что-то такое замутить. Спасибо, ТС.

Обязательно нужны следующие главные документы.
1. Сценарии поведения системы (use cases)
(Пользователь нажал на такую-то кнопку, фронтенд сделал такой-то HTTP запрос, сервер сделал такой-то SQL запрос, сервер вернул такой-то ответ, фронтенд отобразил результат. В случае сбоя сервер вернул другое, фронтенд отобразил другое)
2. Сценарии тестирования системы (test cases)
Тоже самое, только ведут QA.

Писать 900000 страниц абстрактного бреда в документации не нужно, всё равно от этого с ума все сойдут. Только сценарии поведения.

Стандартно
1. FAQ по всем бизнес-процессам с картинками взаимодействий
2. Документация по технической стороне
3. Change requests + Legal requirement — оформляются через Proposal, TDD, FDD + изменение FAQ
4. Тикеты от кастомеров тоже сохраняются + меняется FAQ, если нужно

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

Вот с проекта на 10М строк кода www.chromium.org/...​velopers/design-documents

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

Должны быть картинки со структурой программы (какие модули есть и как они взаимодействуют). Должно быть структурированное описание АПИ (бекенда). Должны быть типовые диаграммы последовательностей.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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