В прошлом посте я написал кучу умных слов. А теперь решил показать практическое применение. Случайно, да.
Как и у любой компании, у нас есть свой почтовый сервер. На нем крутится куча доменов и постоянно кипит жизнь.
Но регулярно к нам приходят пользователи со словами “я тут час, день, месяц назад отправил письмо, а оно не пришло”. Обычно да, прокатывают стандартные ответы “посмотрите в спаме” или “по логам оно было принято ТЕМ почтовым сервером, а куда потом делось мы уже не можем знать”.
Но попутно у меня возник вопрос: а на самом деле, какова реальная задержка в доставке почты ? Задержка – это от момента, когда исходный сервер уже проверил письмо, прошел все правила типа рассылок и до момента, когда удаленный сервер ответил что-то типа 250: Queued for delivery …
Взял логи за последний месяц, пара строчек в консоли, потом из-за недостатка опыта полчаса возни с gnuplot. И вуаля!
Для красоты картинки отсек все задержки, на которые не нашлось хотя бы одной тысячи писем. А то иначе бы пришлось логарифмическую шкалу вводить, ибо у нас есть письма с задержкой в сутки-двое.
Неплохо, я как-то думал, что письма дольше ходят …
Где отчет по загрузкам фиговины с хреновины за последний месяц? Мы его 26 секунд назад должны были послать! Заказчик в потолок кричит уже!
Или нет, лучше вот так:
Вот написал я совершенно шикарную (по моему скромному мнению) штуковину. Всем хороша штуковина: может делать так, а может делать сяк. Выложил я эту штуковину в интернет, а народ возьми и начинай спрашивать: а как этой штуковиной пользоваться-то? Где руководство пользователя, администратора и еще кого-нибудь?
Да не вопрос! Открыл новую вкладку в IDE, вдохновился и описал свой шедевр. Вернее, попытался описать. Диаграммку надо вот тут вставить, а вон там без скриншота не обойтись …
Так, добавляем нужные теги в файл, меняем его расширение в html. Все, готово! Еще надо в PDF? Ставим виртуальный принтер и печатаем на него. Как картинки поехали? Переносим написанное в Word или LibreOffice. Заказчик зубчиками недоволен? Данные для диаграмки поменялись? Скриншотик поменять надо? А-а-а-а … Отвалите от меня! Все, нету больше документации! Вон остатки валяются, пусть технический писатель мучается, ему за это деньги платят!
Знакомо? Думаю да. Любой, кто прикасался к описанию чего-либо, готов часами материться от совместимости форматов, стилей, шрифтов и прочих ужасов. А если подобное надо делать регулярно и еще совместно с кем-нибудь …
Все, мощнейшая демотивация обеспечена. А это неправильно. Тут я пишу про обратное, поэтому нефиг тут. Будем исправлять ситуацию.
Итак, сначала возьмем и взглянем сверху на описанные вначале задачи, которые убивают у нас всякую мотивацию их делать.
Задача 1: Регулярно отправлять Заказчику (Акционеру, Руководителю, Министерству, еще кому-нибудь) какой-нибудь Очень Важный Отчет. В отчете должны быть Очень Важные Цифры, и График, построенный по этим цифрам.
Задача 2: Задокументировать выполненный проект. На выходе должен получиться удобочитаемый документ, с диаграммами, отображающими получившуюся структуру, с форматированным текстом и вообще что бы выглядело не стыдно.
Усложняем задачи тем, что над ними работает не один человек, желательно результат получить в нескольких форматах и все полученное сохранить для потомков. Прибьем сверху условие, что все работают под разными платформами и посмеемся над полученным.
Как решают такие задачи? Очень просто: назначают крайним Васю, сваливают ему в почту данные или логины-пароли для получения этих данных и забывают об этом. Вася в силу своих знаний, громоздит конструкцию из компонент офиса с визио (можно заменить на либроофис и диа) и потерзав участвующих, выдает результат. Затем Васе вынимают оставшиеся мозги правками и затихают до следующего раза. Про систему контроля версий вспоминают тогда, когда уже все похерено. Предложение выложить созданное на веб-сайт все объединенными усилиями топят, ибо весь процесс по-хорошему надо повторить, но уже с другими инструментами, иначе на выходе будет гавно.
Как ни странно, для таких задач давно существует целый класс программ “то, что у вас в уме, то вы и получите”. Задача их состоит в том, что бы взять исходный текст и оформить его согласно правилам для того или иного выходного формата. Надо выложить на веб-сайт? Отрисовываем картинки в низком разрешении и генерируем html. Надо подготовить для печати? Перегенерируем рисунки в большом разрешении и выводим все в eps или pdf. Надо сделать справку для программы? Выбираем нужный формат и все.
Легкий поиск по гуглу легко обрушивает на нас ворох ссылок. Если вам некуда девать деньги и вы работаете только под Windows, то Help&Manual практически однозначный выбор (Helpinator тоже ничего). Если вы дружите с php, то взгляните на отечественный BullDoc, питонистам пригодится Sphinx и так далее.
Люди, давно живущие в интернете, тут же предложат какой-либо движок на Wiki с соответствующими плагинами. В общем, вариантов море.
Давайте я уточню условия:
– Эта штука должна максимально хорошо дружить с системами контроля версий.
– Эта штука должна быть максимально приспособлена под “пользователя тупого, необученного”. У меня нет желания лазить по очередному скоплению менюшек или рассматривать многотомное руководство по языку.
– Эта штука должна быть максимально рассчитана под групповую работу. Когда одну часть документа делает Вася, а другую Петя.
– Эта штука должна максимально автоматизироваться. Я ленивый.
– Бесплатность – это хорошо. Но можно и денег дать, если что.
Снова гугл, снова подбор умных и не очень слов, как внезапно взгляд натыкается на то, что есть в каждом дистрибутиве линукса и доступно в виде установщиков под все остальные платформы.
Итак, за основу я предлагаю взять asciidoc. Есть для всех платформ и четко следует unix-идеологии выполнять хорошо только одну задачу. На входе обычный текст, а на выходе, особенно с использованием других программ, что угодно: от разметки для какой-нибудь wiki до pdf. После краткого просмотра команд становится непонятно, а почему раньше этим не пользовался …
Рисуночки и диаграммки отдадим на откуп gnuplot и graphviz. Они работают аналогично.
Решение задачи 1
Любым способом получаем так нам необходимые данные. Вытаскиваем руками из базы, пишем скрипт для сбора с оборудования, создаем большую таблицу в экселе. И сохраняем их в обычный и привычный всем csv формат. Скажем, мы получили вот такие данные:
Скажем, первый столбец означает число кирпичей, а второй объем выпитого кофе. Очень важные и секретные данные.
Для начала напишем, какие графики мы желаем построить по этим данным:
Очень нечитаемое, да? А в результате команды gnuplot for_gnuplot мы получим вот такую вот картинку в формате svg (формат можно и поменять), которую можно засунуть куда угодно.
Это я так, не выпендривался. Но если что, можно в этой картинке поменять все. От типа линий и заканчивая тем, чем будут рисоваться столбики.
Теперь точно таким же образом опишем сам отчет.
Правда, тут выяснилось, что я раньше сделал две ошибки: во-первых, есть проблемы с отображением svg inline, а во вторых, я как-то не нашел, как заставить asciidoc пропустить первую строчку в csv файле. Обе эти проблемы решаются просто, но мне уже лень переделывать скриншоты. Но в итоге получаем вполне симпатичный html.
Можно дальше его допиливать, а можно и так оставить.
Теперь осталась сущая мелочь: засунуть это в планировщик задач и наслаждаться автоматически отправляемыми отчетами.
К решению задачи 2 мы добавим еще одну программу – graphviz. Она шикарно умеет рисовать всякие диаграммки.
К примеру, нам надо нарисовать схему взаимоотношений в коллективе.
Одна команда и получаем:
Более того, команды для graphviz можно вставить прямо в исходники для asciidoc.
Шикарно? Шикарно!
А ведь я даже не упомянул и 1% возможностей этих программ. Хотя большинству и этого процента хватит за глаза.
А ведь все исходные данные в plain text, что очень понравится использующим системы контроля версий. И все замечательно скриптуется, что еще больше понравится таким лентяям как мне …
