Как хранить архитектуру системы?

Question

[ericcartman]

Как правильно хранить архитекутру программного обеспечения и предоставилять по запросу заинтересованных лиц? Интересуют лучшие практики.
Вариант "лежит презентаха на сетевом диске, кто хочет тот и смотрит" я и сам знаю.

( Дисклаймер 1: кому кажется что я недогуглил, недоработал, задал слишком широкий / узкий / некорректный вопрос, большая просьба - просто пройдите мимо. Будете писать гневные посты - будет ответ)
( Дисклаймер 2: сложность вопроса ставлю среднюю всегда, поскольку ответа я не знаю, следовательно для меня он сложный. А тот кто знает ответ - для того он простой. Вот и выбрал среднее арифметическое)

Comments

[Станислав Б]

Будете писать гневные посты - будет ответ

ах, я не удержался.
Вы что, первый раз в интернете?
Если вы напишите что-то в духе "Если вам кажется что я не прав - уёдите отсюда. Иначе вам ататата"
То даже те, кто и не собирался ничего писать, обязательно напишут.

[Евгений Шатунов]

ericcartman

Как правильно хранить архитектуру программного обеспечения

Хранить надо надежно и бережно, с любовью и заботой. :)

Существует такой термин как "Проектная документация". Этот термин хорошо известен в каждой области деятельности, от кулинарии и до строительства.
Изучи вопросы типовой проектной документации (ТП, как ни странно) и единого стандарта программной документации (ЕСПД).

[ericcartman]

Евгений Шатунов, непременно изучу. Надеюсь что они не 30 лет назад были написаны. Но вот сегодня прямо горит положить архитектурные документы в правильное место, иначе завтра мне придется изучать уже хедхантер на предмет вакансий

[Евгений Шатунов]

ericcartman , а ты понимаешь, не в давности вопрос. ЕСКД - стандарт конструкторской документации - был разработан еще в союзе, а используется до сих пор. И всякие там Компас-3D или SolidWorks очень удобно ложатся на шаблон ЕСКД. А проектная документация на строительство зданий уже давно и полностью выполняется в CAD системах, не изменившись по своей сути с прежних времен.
ЕСПД я читал еще с пожелтевших страниц бумажного справочника по документации, но стандарты оформления внешней документации, внутренней документации, логических и блочных схем (UML) были детально описаны уже тогда.

[ericcartman]

Евгений Шатунов, понимаю. Но мне надо понять, куда положить архитектурные документы, а не стандарты оформления. То есть куда мне их скопировать / залить / послать. Чтобы они там лежали.
Ну как пример: положить в VCS ( например гитлаб). Вот что меня интересует, а не блочные схемы ЮМЛ ( схемы я уже нарисовал в документе)

[Максим Федоров]

ericcartman,

Ну как пример: положить в VCS ( например гитлаб). Вот что меня интересует, а не блочные схемы

Простите НЕэкстрасенсов... Просто вы:

кому кажется что я <...> задал слишком широкий <...> вопрос

...
Для доки хорошо подходит Confluence (от Битбакета)-- там тестировщики, QA и вообще все базу знаний и структуры проектов хранят, но он платный...

Answer 1

[kn0ckn0ck]

Я рекомендую архитектуру описывать при помощи PlantUML, преимущества:
1. это настоящий UML
2. это модель через текст - видим картинку, но всегда можем отредактировать, не нужно идти в тул, где нарисовали и искать там.
3. это бесплатно и поддерживается многими вики или инструментами совместного создания документации

А вот пример, как это должно выглядеть:

Comments

[ericcartman]

а после того как сделали, в какое место положить? к себе на комп, диск С/Мои документы?

[kn0ckn0ck]

читаем еще раз: "поддерживается многими вики или инструментами совместного создания документации"
то есть потом как сделали оно хранится в базе знаний (базе данных), на веб-сайте, как угодно

Answer 2

[Losted]

В моей компании принято хранить документы в Конфлюенсе. Диаграммы делаем в lucidcharts. Так что расшарить диаграмму или спеку - тривиальная задача.