Было бы очень здорово. Наверное, уже имеется классификация схем и некоторое представление о том, что такое схема схем — схема, которая связывает воедино схемы различных уровней. Ведь, это первое, что приходит в голову, что есть разные уровни, и на каждом уровне своя схема.
Да, "схема схем" действительно первой приходит в голову. Хотя в нашем случае не всегда такое нужно. Часто нужны именно отдельные схемы, которые описывают проект с какой-то стороны. Не уверена, что здесь применима уровневая система. Но для некоторых больших проектов конечно прямо просится что-то такое. Мы рассматривали методологию c4 и некоторые готовые редакторы на ее основе. Но пока не придумали как можно ее приспособить для наших схем, она всё-таки больше рассчитана на разработку. Как еще один вид схем - да, применяли. Но не более.
Общая схема работы — это описание того, ради чего функционирует система, где выражена основная системная функция. Разве не так?
Тут видимо вопрос терминологии. В нашей, общая схема работы - это схема, которая отображает устройство инфраструктуры проекта, взаимосвязи внутри нее. У нас нет цели описать ради чего функционирует система. Скорее цель показать как взаимодействуют элементы внутри нее.
Разве для схем не существует ГОСТ?
Наверное смотря для каких схем.
Здесь ожидается описание того, как это всё (эффективно) хранится в базе данных, какие средства визуализации используются/разработаны, какие принципы управления схемами и элементами схем выработаны.
Да, ожидается, но пока этого нет;)
В идеале, схемы развиваются вместе с разработкой системы. Где-то схема идёт впереди разработки, указывая то. что нужно сделать. Где-то схема идёт позади разработки, фиксируя то, как это было реализовано.
Тут сказывается специфика наших схем - мы рассматриваем ту инфраструктуру, которая уже есть в клиентском проекте. Также может быть схема, которая описывает как будет выглядеть проект (или его часть) после предлагаемых изменений. Но мы не работаем совместно с разработкой.
Ага! Вот но что. Вот с этого места, пожалуйста, по подробнее.
Могу в качестве примера привести вот такой редактор, который мы рассматривали. Не реклама, если что, просто привожу для иллюстрации о чем речь. Он вроде позволяет создавать схемы, которые меняются одновременно с изменениями в коде. Скажу честно, что мы его только рассматривали, но никак не применяли у себя.
Автоматические проверки это действительно классная идея. Но мы пока, к сожалению, о таком не задумывались. Про линтеры, и в частности Vale, я не слышала. Теперь стало интересно в этом разобраться, надо покопаться в этой теме. Спасибо.
В целом, про ГОСТы я написала. Просто не стала уточнять какие именно обычно используются. Согласна, что оформление статей это не самая важная часть, наполнение важнее, но в нашем стайлгайде как раз этому моменту мы уделили не мало внимания. В разделе, где описывается структура статей и разделов документации мы расписали какие статьи обычно требуются и что ожидается внутри. А в прошлой статье рассказывали о том, что также создавали для некоторых статей шаблоны.
Да, актуальность это важный фактор. Так как проектов у нас на поддержке много, то просто так постоянно обновлять их все задача слишком трудозатратная. У нас это частично решено тем, что создание документации встроено в жизненный цикл поддержки клиентских инфраструктур. Например, когда новый клиент приходит на поддержку, проводится аудит инфраструктуры и одним из этапов аудита является создание документации. Или если в инфраструктуру вносятся изменения - например, принимается на поддержку новый сервер, то в рамках принятия вносятся изменения и в документацию. В общем каждый раз есть какой-то фактор, который запускает инициацию обновления документации проекта.
На самом деле в ближайшее время у нас выйдет статья про жизненный цикл документации, где об этом будет подробнее рассказано.
Да, "схема схем" действительно первой приходит в голову. Хотя в нашем случае не всегда такое нужно. Часто нужны именно отдельные схемы, которые описывают проект с какой-то стороны. Не уверена, что здесь применима уровневая система. Но для некоторых больших проектов конечно прямо просится что-то такое. Мы рассматривали методологию c4 и некоторые готовые редакторы на ее основе. Но пока не придумали как можно ее приспособить для наших схем, она всё-таки больше рассчитана на разработку. Как еще один вид схем - да, применяли. Но не более.
Тут видимо вопрос терминологии. В нашей, общая схема работы - это схема, которая отображает устройство инфраструктуры проекта, взаимосвязи внутри нее. У нас нет цели описать ради чего функционирует система. Скорее цель показать как взаимодействуют элементы внутри нее.
Наверное смотря для каких схем.
Да, ожидается, но пока этого нет;)
Тут сказывается специфика наших схем - мы рассматриваем ту инфраструктуру, которая уже есть в клиентском проекте. Также может быть схема, которая описывает как будет выглядеть проект (или его часть) после предлагаемых изменений. Но мы не работаем совместно с разработкой.
Могу в качестве примера привести вот такой редактор, который мы рассматривали. Не реклама, если что, просто привожу для иллюстрации о чем речь. Он вроде позволяет создавать схемы, которые меняются одновременно с изменениями в коде. Скажу честно, что мы его только рассматривали, но никак не применяли у себя.
Мы используем редактор draw.io.
Фреймворки, которые вы указали, пока даже не рассматривали. Спасибо за комментарий, обязательно поизучаем их.
Автоматические проверки это действительно классная идея. Но мы пока, к сожалению, о таком не задумывались. Про линтеры, и в частности Vale, я не слышала. Теперь стало интересно в этом разобраться, надо покопаться в этой теме. Спасибо.
В целом, про ГОСТы я написала. Просто не стала уточнять какие именно обычно используются.
Согласна, что оформление статей это не самая важная часть, наполнение важнее, но в нашем стайлгайде как раз этому моменту мы уделили не мало внимания. В разделе, где описывается структура статей и разделов документации мы расписали какие статьи обычно требуются и что ожидается внутри. А в прошлой статье рассказывали о том, что также создавали для некоторых статей шаблоны.
Да, актуальность это важный фактор. Так как проектов у нас на поддержке много, то просто так постоянно обновлять их все задача слишком трудозатратная. У нас это частично решено тем, что создание документации встроено в жизненный цикл поддержки клиентских инфраструктур. Например, когда новый клиент приходит на поддержку, проводится аудит инфраструктуры и одним из этапов аудита является создание документации. Или если в инфраструктуру вносятся изменения - например, принимается на поддержку новый сервер, то в рамках принятия вносятся изменения и в документацию.
В общем каждый раз есть какой-то фактор, который запускает инициацию обновления документации проекта.
На самом деле в ближайшее время у нас выйдет статья про жизненный цикл документации, где об этом будет подробнее рассказано.