Автоматические проверки это действительно классная идея. Но мы пока, к сожалению, о таком не задумывались. Про линтеры, и в частности Vale, я не слышала. Теперь стало интересно в этом разобраться, надо покопаться в этой теме. Спасибо.
В целом, про ГОСТы я написала. Просто не стала уточнять какие именно обычно используются. Согласна, что оформление статей это не самая важная часть, наполнение важнее, но в нашем стайлгайде как раз этому моменту мы уделили не мало внимания. В разделе, где описывается структура статей и разделов документации мы расписали какие статьи обычно требуются и что ожидается внутри. А в прошлой статье рассказывали о том, что также создавали для некоторых статей шаблоны.
Да, актуальность это важный фактор. Так как проектов у нас на поддержке много, то просто так постоянно обновлять их все задача слишком трудозатратная. У нас это частично решено тем, что создание документации встроено в жизненный цикл поддержки клиентских инфраструктур. Например, когда новый клиент приходит на поддержку, проводится аудит инфраструктуры и одним из этапов аудита является создание документации. Или если в инфраструктуру вносятся изменения - например, принимается на поддержку новый сервер, то в рамках принятия вносятся изменения и в документацию. В общем каждый раз есть какой-то фактор, который запускает инициацию обновления документации проекта.
На самом деле в ближайшее время у нас выйдет статья про жизненный цикл документации, где об этом будет подробнее рассказано.
Автоматические проверки это действительно классная идея. Но мы пока, к сожалению, о таком не задумывались. Про линтеры, и в частности Vale, я не слышала. Теперь стало интересно в этом разобраться, надо покопаться в этой теме. Спасибо.
В целом, про ГОСТы я написала. Просто не стала уточнять какие именно обычно используются.
Согласна, что оформление статей это не самая важная часть, наполнение важнее, но в нашем стайлгайде как раз этому моменту мы уделили не мало внимания. В разделе, где описывается структура статей и разделов документации мы расписали какие статьи обычно требуются и что ожидается внутри. А в прошлой статье рассказывали о том, что также создавали для некоторых статей шаблоны.
Да, актуальность это важный фактор. Так как проектов у нас на поддержке много, то просто так постоянно обновлять их все задача слишком трудозатратная. У нас это частично решено тем, что создание документации встроено в жизненный цикл поддержки клиентских инфраструктур. Например, когда новый клиент приходит на поддержку, проводится аудит инфраструктуры и одним из этапов аудита является создание документации. Или если в инфраструктуру вносятся изменения - например, принимается на поддержку новый сервер, то в рамках принятия вносятся изменения и в документацию.
В общем каждый раз есть какой-то фактор, который запускает инициацию обновления документации проекта.
На самом деле в ближайшее время у нас выйдет статья про жизненный цикл документации, где об этом будет подробнее рассказано.