One pandoc to rule them all

👌🏽

Есть ещё прикольные комиксы от компании редхат про контейнеры в линуксе https://github.com/fedoradesign/coloringbook-containers/blob/master/Print-Ready/Pages.A4.pdf

Документация как комиксы

Когда мне было четыре или пять лет, мама подарила мне книжку комиксов «Откуда берутся дети». Я прочитал, всё понял и в следующие лет 7-10 знал точно больше своих сверстников. Конечно, потом были и другие источники, но тот комикс дал мне начальные знания и избавил от кучи недоразумений.

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

— «Приятного плавания с Kubernetes».  
Древнегреческий мореплаватель Ясон теперь работает в IT и руководит отрядом боевых админов. Это сложнее, чем засевать поля драконьими зубами. Богиня Гера знакомит его с «κυβερνήτης», «рулевым». Конечно, Рулевой решает сразу все проблемы Ясона — это же сказка, а в сказке так бывает.

— Как работает DNS.  
DNS-запрос путешествует в поисках IP-адреса.

— Как работает HTTPS.  
Сертификот и другие звери рассказывают о том, как защитить сообщения в интернете от злонамеренных крабов.

---

Кстати, от того же корня, что и «кубернетес», образованы слова «губернатор» и «гувернёр».

Знаете другие примеры хорошей документации в картинках? Приходите обсудить их в @docsascode.

В целом грустно, что приходится такое комиксами делать

Почему же?

Для школьников вполне можно так объяснять

Кубернетес школьникам?

Ну и это конечно оскорбительно уже для средней школы

Кому-то понятнее сначала в картинках посмотреть. Для тех имеет право существовать.

В рамках обязательного курса давать это было бы непедагогично:
1) Тяжело привязать к контексту задач, чтобы человек понял, как конкретно применить знания
2) Слабая связь с имеющимся опытом, т.к. объясняется с нуля, на пальцах
3) Нужно иметь в виду аудиторию, иначе может быть оскорбительным

А так, сосласться на вводной лекции, чтобы кто-то "пощупал", вполне рабочий подход

у гугла есть комикс про кубернетес и хелм шикарный

+++

зря вы недооцениваете комиксы

Комикс с контейнерами насколько я знаю делали для стенда на профильной конференции. И если быть точным, то это был не комикс, а сказка в картинках для раскраски. Там где расдавали такие книжки не было людей которым надо такие вещи в цветных картинках рассказывать 🙂 это был то ли LinuxCon, то ли Linux Plumbers. Поэтому повода для грусти не вижу.

+

Возможно у человека был негативный опыт, когда именно приходилось объяснять на таком уровне, оттого и грусть 🙂

Особенно когда формально ты ещё не лид, и нужно партизански устраивать обучение, чтобы решить какую-то другую задачу — это может сильный отпечаток оставить

Питер, отзовись!
Мы делаем митап про разработку в формате Lean Coffee и ищем техписов, которые готовы помочь с конспектированием бесед.
Ссылка на мероприятие: https://piterpy.timepad.ru/event/886097/
Пример бомбового конспекта от @Nick_Volynkin: https://github.com/NickVolynkin/ritfest18-community-meetup

Уважаемые господа присутствующие!
Прошу помочь с таким простым и сложным вопросом: в чём сейчас ведут документацию по проектам серьёзные конторы?
Я объясню: мы сначала хотим задокументировать логику нашего внутреннего кода (просто блок-схемы или замахнуться на UML?).
Но у нас есть и второй этап: это документирование бизнес-процессов на предприятии в целом.
Потом, третьим этапом, возможно, и постановку задач делать по каким-то стандартам (а не кодить, а потом писать доку)).
Но пока главное - это, конечно, первый этап, хотя и с поглядыванием вдаль... -)
Хотелось бы не изобретать велосипед, а использовать передовые решения.
В чём описывать код и бизнес-логику? Стандарт и хорошие средства для этого стандарта...

любимый ответ этого чата: в репозитории на языках разметки)