Познакомимся с подходом Docs as Code, предлагающим использование инструментов разработчика для написания текстов различной природы от технической документации на приложения, сервисы, цифровые продукты до статей, учебных курсов, блог-постов
В багаже было пара дней и необходимость попрактиковаться в процедурах Docs as Code. Курс представляет собой последовательное выполнение действий по разработке спецификации базовых эндпойнтов условного сервиса с помощью разметки AsciiDoc. С AsciiDoc ранее не работал, так что погрузился с интересом. Но курс достаточно скоротечный - при желании можно за несколько часов пройти - и, как было написано выше, последовательный. Т.е. ты, как разработчик документации, идёшь по контролю версий с инициализации репозитория до публикации и сборки кода-документа на гитхабе. Поэтому если непонятно, как устроен контроль версий (не только git), то имхо лучше про него почитать/поупражняться. Ибо git суть базовый элемент процесса.
Повторю, курс скоротечный, но предельно понятный. Т.е. такой базис-базис. Из пожеланий хотелось бы рекомендовать рассмотреть вопросы работы над документами (и разными разделами одного документа) более чем одним специалистом. Также интересны более сложные случаи с откатом изменений (это прямо актуальная проблема) в контроле версий. На мой взгляд, это решается более глубокими задачами, а не как сейчас задачей в духе "продолжить команду ....".
П.С. И ещё обращу внимание будущих студентов, что автоматически переложить полученные знания для применение Markdown в связке с GitHub не получится (с GitLab вроде должно прокатить).
На момент выбора курса, альтернатив просто не было. Разработчикам курса спасибо. Критиковать что-то уже имеющееся проще, чем создать что-то с нуля.
Вот немного критики:
Хотел было посоветовать курс техническому писателю, но потом понял, что не поймет. Не для новичков. Курс должен предъявлять требования к уже имеющимся у слушателя навыкам. Это умение хоть как-то работать в командной строке Linux, знание Git и основы программирования (ну хотя бы начальное понимание).
Из плюсов:
Показан последовательный процесс написания этих самых "docs". Дает понимание как doc-as-code работает изнутри.
Для старта в этой области курс неплохой.
Курс разочаровал по нескольким причинам:
1. Слишком много кейсов с крошками обучения
Вместо структурированного обучения — набор примеров. Ожидала больше теории и пошаговых инструкций, но получила, скорее, код выдранный из контекста
2. Не для новичков
Материал подаётся так, будто мы уже знакомы с разметкой, Git-ом, HTML. Без базовых знаний сложно понять логику (ну тут нас предупреждали в описании)
3. Минимум полезного контента
Отсыпали нам ссылок на Asciidoc и Git. Читайте!) Хотелось бы больше практических разборов: как настроить конкретный инструмент, как интегрировать его в рабочие процессы, какие подводные камни возможны
Итог: курс может быть полезен тем, кто уже работает с Docs as Code и хочет изучить чужие кейсы. Но для новичков или тех, кто ждёт системного обучения, — не подходит. Поверхностно поплавала, поплакала (деняк жалко), пошла дальше
И почему никто не пишет про грамматические ошибки в курсе для тех писов?))
Спасибо за отзыв! Жаль, что курс оказался для вас недостаточно полезным.
По комментариям. Как указано в описании, курс строится на базе конкретного кейса. Он ориентирован на практику. Не на теорию.
По поводу грамматики. Вы можете оставить комментарий там, где не согласны с формулировками. Так поможете сделать курс лучше
Курс помог потренироваться и посмотреть на весь процесс от создания документации в asciidoc до публикации на github.
У тех, у кого Windows, действительно, как писали другие коллеги, лучше установить VM и на нее Ubuntu. По началу, кажется сложно, но комментарии коллег под некоторыми шагами и chatgpt спасали.
Для меня курс был полезный.
Курс понравился. Является хорошим "быстрым стартом" в направлении docs-as-code. Хорошо, что показан end-to-end процесс.
Если вы работали только на Windows, то посоветовал бы установить на виртуальную машину Ubunty, а на ней Git. И немного освоиться с Ubunty и с её терминалом. В курсе показаны команды, которые будут работать в *nix системах.
Хороший курс.
Чуть резкий вход без объяснения как все настроить, чтобы работало на Windows, но во всем можно разобраться.
Но в целом весь подход на простых примерах описан от и до.
