Пока мы не сталкивались с проблемами скорости сборки - на наших документах укладываемся в разумное время. Но ваш опыт с precompiled headers очень интересен, спасибо за наводку (вот она - сила Хабра, когда в комментариях появляются ценные идеи). Можете поделиться примерными замерами, насколько ускорилась у вас сборка? Для ускорения можно еще попробовать выносить статичные части документа в отдельные .pdf и подключать через \includepdf. В нашем шаблоне затратна по времени генерация диаграмм из текстового описания, поэтому при билде проверяем, если диаграмма уже была ранее сгенерирована в отдельный pdf, то повторно не перегенерируем ее, а берем уже готовую.
Спасибо за ссылку, приложение многообещающее, еще и open source! Здорово, что есть поддержка популярных диаграмм и графики (Mermaid, PlantUML, Draw.io) и вообще выглядит очень дружелюбно. Попробуем, для небольших и средних док выразительных возможностей точно хватит. Но и LaTeX не забросим - понравились нам возможности полной настройки и автоматизации )
Да, документация в коде (Doxygen) здорово дополняет docs-as-code! Но есть еще архитектурные решения, диаграммы потоков данных, гайды по онбордингу и интеграции, спецификации и подобное - вот тут LaTeX очень хорошо подходит. LaTeX внутри комментариев - звучит интересно, кажется подойдет там, где требуется действительное подробное описание происходящего, мы не пробовали, у нас не было такого rocket science )
PDF тут скорее не про печать на бумагу, а про строгую вёрстку, которая не плывет как веб-интерфейс. И да, мы неоднократно сталкивались с требованиям о предоставлении документации именно в виде PDF. А LaTex можно преобразовать и в HTML (через Pandoc), главное тут единый источник - .tex файл (что соответствует общему принципу docs-as-code), а выходной формат можно менять.
Спасибо за наводки, Org Mode и Texinfo действительно выглядят как мощные инструменты! У нас никто не использовал Emacs, поэтому мы пошли путем LaTeX.
Если честно - не жаль. Жаль, когда в документации WYSIWYG после переноса картинки или добавлении в табличке новой строки начинает все ехать. Особенно больно, когда дока не на страничку, а на 100 - и одна микроправка убивает часы ручного форматирования.
В общем, зависит от объема и навороченности документации: для небольших документов можно обойтись и простыми решениями, но чем сложнее и объемнее документация, тем больше времени вы будете терять на борьбу с WYSIWYG-редакторами вместо собственно работы с содержанием. Мы считаем, что затраты окупаются, так как результат получается "красивым" и предсказуемым. Но, каждой задаче - свой инструмент.
В нашем кейсе заказчик попросил именно LaTeX - поэтому другие варианты сразу отпали. А потом мы поняли, как LaTeX можно использовать еще - старт с готовым шаблоном оказался проще, чем разбираться с новой технологией.
Но про docbook до сих пор не слышали, посмотрим. Спасибо за рекомендацию!
Согласны про больше интеграционных. Мы тут под Unit подразумеваем не всегда самую маленькую и ни от чего независящую единицу. Мы сейчас тоже перешли к большему количеству интеграционных тестов + минимум E2E-тестов самого API, которые заменяют каноничные Unit-тесты..
А у нас достаточно опыта в .NET и насмотренности в других стеках, таких как Python, NodeJS, C/C++. Один из авторов, который вам сейчас пишет - Александр, начинал профессиональную карьеру на C# 13 лет назад, читал Рихтера, Фаулера, Мартина и т.д., делал проекты, ездил учиться на конференции DotNext, а сейчас и сам делится знаниями и видением.
Для нас так стало проще и интереснее, и веселее :)
В отдельной статье поделимся тем, как именно пишем тесты на бекенды, напсанные на .NET, на каких слоях пирамиды тестирования, используя какие инструменты и подходы.
Здесь хотели поделиться идеей, её плюсами и техническими деталями реализации.
Классный совет! Спасибо, мы попробуем :) 12 лет назад пользовались Razor и Web.config со всеми их скрытыми вложенностями, что-то не подумали, что такая фича всё ещё должна быть и прикольно работать.
Интересный вопрос: сделает эта штука Development Experience лучше или нет. В том плане, что надо будет расхлопнуть файл, чтобы увидеть, что к нему есть привязанный тест, по этой причине также не любим регионы, куда прячутся портянки кода. С другой стороны, это компактнее.
Вы правы, для чувствительных данных, таких как логин, пароль от базы данных, нужно использовать как минимум env переменные. Не добавили этого в статью, чтобы не усложнять пример. Чтобы попробовать фичи - достаточно скопировать и вставить, без создания переменных, откуда будут браться логины и пароли. Что насчет портов: мы указали порт для базы данных, чтобы иметь возможность подключиться к ней из API, запущенного в IDE. Спасибо за совет, посмотрим в сторону бинда на локальный хост :)
Да, отличная идея добавить healthcheck. Мы используем эту фичу в наших других проектах, но для простоты примера не добавили её в статье, чтобы сфокусироваться на представленных выше фичах. Спасибо за совет!
Да, вы правы, можно использовать внешнюю переменную окружения. Но мы выбрали этот кейс как простой пример использования шаблонов сервисов. Нам, например, может понадобиться изменить скрипт в одном из копий сервиса, и для того, чтобы не копировать весь сервис, используем шаблон Спасибо за совет о docker compose, учтем!
Можно поставить любые расширения в связке ide+docker-compose, но тогда их либо придется ставить внутрь контейнера + vs code туда же, либо, если использовать docker-compose чисто для сборки и билда, расширения придется ставить локально. Dev контейнеры же легко позволяют устанавливать расширения именно в контейнер.
Зависит от того, что вам нужно. Мы, например, используем расширения VS Code для поддержки синтаксиса языка, для удобного взаимодействия с Cmake, для написания документации и поддержки Mermaid и многие другие. Удобно, когда нужное расширение одним кликом можно добавить в контейнер.
Пока мы не сталкивались с проблемами скорости сборки - на наших документах укладываемся в разумное время. Но ваш опыт с precompiled headers очень интересен, спасибо за наводку (вот она - сила Хабра, когда в комментариях появляются ценные идеи).
Можете поделиться примерными замерами, насколько ускорилась у вас сборка?
Для ускорения можно еще попробовать выносить статичные части документа в отдельные .pdf и подключать через
\includepdf. В нашем шаблоне затратна по времени генерация диаграмм из текстового описания, поэтому при билде проверяем, если диаграмма уже была ранее сгенерирована в отдельный pdf, то повторно не перегенерируем ее, а берем уже готовую.Пока только поверхностно ознакомились с Typst. А поделитесь опытом, почему Typst не заменит TeX?
Выглядит как альтернатива LaTeX, но с более простым синтаксисом. Плюс одна полезная ссылка, спасибо за наводку!
Спасибо за отзыв! Рады были поделиться опытом ) Markdown тоже широко используем, а для навороченных док - LaTeX.
Спасибо за ссылку, приложение многообещающее, еще и open source! Здорово, что есть поддержка популярных диаграмм и графики (Mermaid, PlantUML, Draw.io) и вообще выглядит очень дружелюбно. Попробуем, для небольших и средних док выразительных возможностей точно хватит. Но и LaTeX не забросим - понравились нам возможности полной настройки и автоматизации )
Да, документация в коде (Doxygen) здорово дополняет docs-as-code! Но есть еще архитектурные решения, диаграммы потоков данных, гайды по онбордингу и интеграции, спецификации и подобное - вот тут LaTeX очень хорошо подходит.
LaTeX внутри комментариев - звучит интересно, кажется подойдет там, где требуется действительное подробное описание происходящего, мы не пробовали, у нас не было такого rocket science )
PDF тут скорее не про печать на бумагу, а про строгую вёрстку, которая не плывет как веб-интерфейс. И да, мы неоднократно сталкивались с требованиям о предоставлении документации именно в виде PDF. А LaTex можно преобразовать и в HTML (через Pandoc), главное тут единый источник - .tex файл (что соответствует общему принципу docs-as-code), а выходной формат можно менять.
Спасибо за наводки, Org Mode и Texinfo действительно выглядят как мощные инструменты! У нас никто не использовал Emacs, поэтому мы пошли путем LaTeX.
Если честно - не жаль. Жаль, когда в документации WYSIWYG после переноса картинки или добавлении в табличке новой строки начинает все ехать. Особенно больно, когда дока не на страничку, а на 100 - и одна микроправка убивает часы ручного форматирования.
В общем, зависит от объема и навороченности документации: для небольших документов можно обойтись и простыми решениями, но чем сложнее и объемнее документация, тем больше времени вы будете терять на борьбу с WYSIWYG-редакторами вместо собственно работы с содержанием. Мы считаем, что затраты окупаются, так как результат получается "красивым" и предсказуемым. Но, каждой задаче - свой инструмент.
В нашем кейсе заказчик попросил именно LaTeX - поэтому другие варианты сразу отпали. А потом мы поняли, как LaTeX можно использовать еще - старт с готовым шаблоном оказался проще, чем разбираться с новой технологией.
Но про docbook до сих пор не слышали, посмотрим. Спасибо за рекомендацию!
Согласны про больше интеграционных. Мы тут под Unit подразумеваем не всегда самую маленькую и ни от чего независящую единицу. Мы сейчас тоже перешли к большему количеству интеграционных тестов + минимум E2E-тестов самого API, которые заменяют каноничные Unit-тесты..
А у нас достаточно опыта в .NET и насмотренности в других стеках, таких как Python, NodeJS, C/C++. Один из авторов, который вам сейчас пишет - Александр, начинал профессиональную карьеру на C# 13 лет назад, читал Рихтера, Фаулера, Мартина и т.д., делал проекты, ездил учиться на конференции DotNext, а сейчас и сам делится знаниями и видением.
Ещё ребята в Go так делают: https://go.dev/doc/tutorial/add-a-test и вот ещё интересное обсуждение такого подхода, https://www.reddit.com/r/golang/comments/157tsdj/where_do_you_place_your_tests_in_your_project/?rdt=51749.
Если что, мы ещё и не верим в автомаппер и медиатор в .NET проектах =ъ
Пыс: не очень понятно откуда и зачем такой негатив
Проверили, работает, спасибо, будем знать :)
Для нас так стало проще и интереснее, и веселее :)
В отдельной статье поделимся тем, как именно пишем тесты на бекенды, напсанные на .NET, на каких слоях пирамиды тестирования, используя какие инструменты и подходы.
Здесь хотели поделиться идеей, её плюсами и техническими деталями реализации.
Классный совет! Спасибо, мы попробуем :) 12 лет назад пользовались Razor и Web.config со всеми их скрытыми вложенностями, что-то не подумали, что такая фича всё ещё должна быть и прикольно работать.
Интересный вопрос: сделает эта штука Development Experience лучше или нет. В том плане, что надо будет расхлопнуть файл, чтобы увидеть, что к нему есть привязанный тест, по этой причине также не любим регионы, куда прячутся портянки кода. С другой стороны, это компактнее.
Будем пробовать и смотреть, как пошло.
Вы правы, для чувствительных данных, таких как логин, пароль от базы данных, нужно использовать как минимум env переменные. Не добавили этого в статью, чтобы не усложнять пример. Чтобы попробовать фичи - достаточно скопировать и вставить, без создания переменных, откуда будут браться логины и пароли.
Что насчет портов: мы указали порт для базы данных, чтобы иметь возможность подключиться к ней из API, запущенного в IDE. Спасибо за совет, посмотрим в сторону бинда на локальный хост :)
Да, отличная идея добавить healthcheck. Мы используем эту фичу в наших других проектах, но для простоты примера не добавили её в статье, чтобы сфокусироваться на представленных выше фичах. Спасибо за совет!
Спасибо, узнали что-то новое, исправим!
Да, вы правы, можно использовать внешнюю переменную окружения. Но мы выбрали этот кейс как простой пример использования шаблонов сервисов. Нам, например, может понадобиться изменить скрипт в одном из копий сервиса, и для того, чтобы не копировать весь сервис, используем шаблон
Спасибо за совет о docker compose, учтем!
Да, действительно используем docker desktop. Посмотрим в сторону rancher desktop, спасибо :)
Можно поставить любые расширения в связке ide+docker-compose, но тогда их либо придется ставить внутрь контейнера + vs code туда же, либо, если использовать docker-compose чисто для сборки и билда, расширения придется ставить локально. Dev контейнеры же легко позволяют устанавливать расширения именно в контейнер.
Зависит от того, что вам нужно. Мы, например, используем расширения VS Code для поддержки синтаксиса языка, для удобного взаимодействия с Cmake, для написания документации и поддержки Mermaid и многие другие. Удобно, когда нужное расширение одним кликом можно добавить в контейнер.