Корпоративная база знаний это не только и не столько площадка на базе какого-нибудь вики-движка, сколько люди и процессы, стоящие за ней. При внедрении вики-платформы самое сложное это не тонкая настройка движка или попутных расширений: самое сложное это сделать так, чтобы коллеги наконец начали пользоваться поднятой вами базой знаний.

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

Про меня и мою базу знаний

В людях живал свету видал: топор на ногу обувал, топорищем подпоясывался

Ahoj. Меня зовут Коля, я QA тимлидер в компании Veeam. QA в нашей компании включает в себя не только тестирование, но и обеспечение качества в самом широком смысле. И среди этих смыслов затесалась такая штука, как управление знаниями. Я занимаюсь внутренней корпоративной базой знаний компании практически с самого ее появления, при этом поддержка базы знаний не входит в список моих обязанностей: это скорее что-то вроде pet-проекта. Долгое время у вики был статус поделочки, а мои попытки навязать вики коллегам приводили лишь к пополнению корпоративного стикер-пака моей фотографией.

Впрочем, время идет, времена меняются. Сейчас вики насчитывает 700 пользователей, 11 000 страниц, 56 000 правок и 688 000 слов (примерно полтора романа "Война и мир", если говорить только о тексте). Всего-то в 2 000 раз меньше русскоязычной Википедии, и это при условии работы на исключительно добровольных началах: никто не принуждает сотрудников пользоваться нашей вики.

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

Общий подход

Ищи себе прибыли, а другому не желай гибели

Давайте я сразу это проговорю: серебряной пули нет. Все, что я здесь описываю, может сработать, а может не сработать. Не устраивайте из моих советов карго культ. Вы лучше меня знаете своих коллег и лучше понимаете, какой подход подойдет в вашей компании, в вашем коллективе. Есть какие-то более-менее универсальные вещи, но и они в некоторых случаях могут не работать.

Главный совет, который я бы хотел дать в этой статье, звучит так: относитесь к проекту базы знаний как к публичному проекту. Скажем, если бы вы придумали Википедию или Хабрахабр, как бы вы продвигали их в массы? Реклама? Уникальный контент? Холодные как хвост вашей бывшей звонки на случайные номера из телефонной книги? Возможны любые варианты продвижения, но не забывайте адаптировать их к реалиям вашей компании и вашего коллектива. А еще не забывайте, что в случае недобросовестной рекламы коллеги узнают, где вас найти. Не перегибайте палку.

Кроме прочего, подход к вики как к публичному проекту позволяет проще относиться к проблеме продвижения. Я часто слышал обиды и сетования, что, мол, коллеги не делятся знаниями, не пишут внутреннюю документацию. Но вы же не обижаетесь на пользователей за то, что они не скачивают ваше приложение или не покупают ваши чудо-подушки за $9,99? Вы ищете способ понравиться вашим пользователям, ищете путь к их теплокровному сердцу, а не способ подчинить их вашей воле.

С непривычки может быть трудно переложить опыт продвижения публичного проекта на внутреннюю базу знаний, так что я накидаю тех идей, которые сработали в моем случае. Ну, или мне кажется, что они сработали.

Собирайте статистику

Красна птица перьями, а человек знанием

А начнем мы с того, что нам нужно как-то оценивать качество тех способов продвижения, что мы будем пробовать. В связи с этим первое, чем стоит озаботиться это сбор статистики. Скажем, я пользуюсь Matomo (которые раньше звались Piwik), но похожий функционал есть у десятков аналогов.

На мой взгляд, одна из ключевых вещей при сборе статистики это сохранение конфиденциальности. Да, это не гугл, но мало кому будет приятно узнать, что их история посещений доступна вам во всех мельчайших деталях. Отвяжите информацию о посещениях от конкретных пользователей, сделайте эти данные анонимными. Никому не захочется жить под колпаком.

Помимо оценки эффекта продвижения, статистика предоставляет и пачку других плюшек:

• Анализ поисковых запросов решает сразу несколько проблем:

  • Вы понимаете, что людям интересно, что они хотели бы видеть на вики. Если у вас нет статей по теме, которая интересна вашим коллегам, это отличный повод их туда добавить.

  • Кроме того, так вы можете понять, хорошо ли работает поиск, показывает ли он в поисковой выдаче правильные статьи. Если нет, то, возможно, стоит доработать поиск: убрать из индексинга ненужную информацию или добавить дополнительные ключевые слова в статью. А в особых случаях, возможно, имеет смысл задуматься о смене поискового движка.

• Можно добавлять логирование конкретных действий, что позволит вам узнать, как часто пользуются тем или иным функционалом. Так вы не будете вкладывать силы в то, чем абсолютно никто не пользуется. И сможете продвигать базу знаний, подчеркивая в обсуждениях объективно самые популярные фичи.

Накопите критическую массу знаний

Там хорошо, где нас нет

Если вы лишь недавно начали развивать базу знаний, найдите способ наполнить ее контентом.

Вполне возможно, что информация о продуктах, технологиях и фичах уже есть где-то, но в разрозненном неструктурированном виде: почтовые треды, сообщения в Slack/Teams, сетевые папки десятилетней давности, Sharepoint-ы, осколки прошлых неудачных попыток завести единую базу знаний и так далее.

Но будьте внимательны к тому, что вы сохраняете на вики: внутренняя база знаний это источник необщедоступной информации. За общеизвестной информацией проще пойти в Гугл или Википедию, так что подобные статьи скорее всего окажутся мертвым грузом на вашем сайте.

Еще один очевидный источник контента ваши личные заметки и ваши личные знания. Об этом аспекте давайте поговорим поподробнее.

Вам надо вот сами и пользуйтесь

Не ищи в селе, а ищи в себе

Первое время основным пользователем базы знаний скорее всего будете вы сами. С одной стороны, это не особо воодушевляет, но, с другой стороны, вы можете изначально строить базу знаний на тех принципах, что близки и удобны именно вам. Это хорошая позиция для начальных этапов развития портала: если даже вам не хочется пользоваться базой знаний, то почему кто-то другой должен относиться к ней иначе?

Проанализируйте свои потребности: какая информация вам нужна в работе, какие знания значительно ускорили или улучшили бы вашу работу. Информация о сфере ответственности или компетенциях коллег? Детальные описания фичей и внутренних API? Правила оформления отпуска и процедура выпуска релиза? Найдите удобный способ хранить и обновлять информацию такого рода, поделитесь этим с коллегами. Наверняка это было не только вашей болью, но и их тоже.

Ведите заметки о продукте и проектах сразу на вики. Если делитесь инфомрацией, отправляйте не кусок текста, а ссылку на конкретную секцию предварительно созданной вики-страницы. Если вам присылают инфу или рассказывают что-то, запишите на вики инфу об этом. Первое время это может вызывать негатив, но дайте людям привыкнуть к такому способу получения информации.

Сделайте вики единой точкой доступа для поиска любых знаний

И чтец, и жнец, и на дуде игрец

Если ваш интранет полнится десятками сайтов различной направленности, найдите способ выделиться на этом фоне. Например, сделайте вики точкой входа для поиска любых внутренних знаний. Подойти к этому можно с разных сторон:

• Можно сделать просто каталог внутрикорпоративных сайтов (привет, девяностые). Да, подход, мягко говоря, не самый свежий, но и у вас в компании скорее всего не тысячи порталов. Для пары десятков сайтов и каталог обычно подходит неплохо.

• Или же можно идти по пути Гугло-поисковика и встраивать себе поиск по другим сайтам. При этом необязательно писать свой краулер, можно обойтись и более дешевым решением. Например, воспользоваться поисковым API сторонних сайтов и выводить результаты поиска по другим сайтам, если на вашей вики результатов не нашлось.

При этом не забывайте, что поиск "любых знаний" не ограничивается знаниями техническими. Такие вещи, как процедуры оформления отпусков или контакты HR/бухгалтерии/охраны/etc могут оказаться не менее важной частью вашей базы знаний, чем описания фичей или продуктов.

Создавайте зону комфорта для окружающих

Не хвались теплом в нетопленой избе

Очевидный момент, который, тем не менее, многие упускают: неудобной базой знаний пользоваться будут неохотно. Ищите способы упростить работу с порталом, устраняйте неудобства, чините баги, автоматизируйте то, что можно автоматизировать. Вот несколько примеров из личного опыта:

• Сделайте удобную главную страницу. У проектов Викимедиа особый подход к главным страницам, но мне он не нравится: их главные страницы перегружены информацией, они вызывают ужас и непонимание у неподготовленного пользователя.

  На мой взгляд, джентельменский набор любой главной страницы это поле поиска, блок новостей, ссылка на создание новой страницы и несколько ссылок на ключевые разделы. Свою вики я уже показывал в предыдущей статье.

• Стандартизируйте и упростите процесс документирования типовых вещей. Формы и шаблоны позволяют не думать про форматирование и сосредоточиться только на содержании.

  Долгое время у нас никак не документировались скрытые параметры продуктов, и все такие опции хранились исключительно в головах и в коде. Попытки как-то исправить ситуацию бесславно проваливались из раза в раз, пока мой коллега не приделал к вики формы добавления и редактирования документации этих параметров. Уже в первый месяц появилось около сотни описаний параметров, а через полгода документирование параметров на вики стало чем-то вроде негласного правила хорошего тона.

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

  Вам может показаться, что ваши коллеги с тремя высшими легко освоят очередной markdown, и в этом нет большой нужды, но вы ошибаетесь: они могут освоить ваш маркдаун за час, но не хотят. Им это неинтересно, так к чему плодить страдания без необходимости?

• Моя любимая история про поиск. В Veeam используется невероятное количество внутрикорпоративного жаргона, равнодалекого от русского и английского языков. Звучать оно может примерно так: "Задизейбли шедул джобы и чекни базу вана, висит ли флаг". Адаптация к жаргону проходит не очень быстро, но это полбеды. Беда в том, что у разных отделов может отличаться терминология, так что не всегда мы понимаем друг друга. А еще мы почему-то очень любим трехбуквенные аббревиатуры, которых накопилось, наверно, больше сотни (и которые не всегда просто расшифровать).

  В базе знаний этот вопрос решился введением постоянно пополняемого словаря синонимов, аббревиатур и прочего. Словарь используется при поиске, так что пользователь всегда видит, что, например, по запросу "data mover" находится "VeeamAgent" компонент. Составлять словарь приходится вручную, так что иногда доводится выбираться в лингвистические экспедиции для сбора материала в соседние отделы.

  Конечно, остается проблема с тем, что одно и то же слово может означать сразу несколько вещей (скажем, "бекап" это резервная копия, задание резервного копирования, процесс резервного копирования, продукт Veeam Backup & Replication или отдел Backup QA в зависимости от контекста). Это пока что решаем по аналогии с Википедией: создаем страницу с термином и расписываем, что этот термин может значить.

• На большой Википедии вместе с каждой страничкой создается страница для обсуждения. Я же со своей вики все страницы обсуждения убрал: на мой взгляд, реализация дискуссий на Википедии очень плохо подходит для внутрикорпоративных дискуссий. Куда лучше заставить людей пользоваться привычными средствами ведения дискуссий: почта, чаты и звонки в MS Teams. И вопрос решается быстрее, и негатива меньше.

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

Рассказывайте о новостях

Из серебряных речей пулю не отольешь

Никто не узнает о том, какая у вас крутая база знаний, если вы не будете об этом рассказывать. И желательно не один раз. Как говорил один мой университетский преподаватель:

Обычному человеку нужно повторить одно и то же десять раз, прежде чем он запомнит. Однако вы интеллектуальная элита страны, лучшие из лучших. Вам достаточно девяти.

Думаю, нас он на тот момент сильно переоценил, но мысль верная: недостаточно один раз рассказать про существование и назначение базы знаний, обо всем этом нужно периодически напоминать. Чтобы не выглядеть как умалишенный, стоит использовать разные поводы для этого, например:

• Заведите дайджест в почте, в котором вы периодически будете рассказывать о разработке базы знаний: что появилось нового, что починили старого, куда двигаетесь дальше. Если не перебарщивать с письмами, это может быть весьма действенным инструментом продвижения.

• В группах по фиче/продукту/проблеме рассказывайте о новых статьях по теме, написанных вашими коллегами. Русскоязычные айтишники скромный народ, мы обычно не любим хвастаться плодами своего труда. Сделайте это за них: во-первых, авторам будет чертовски приятно, а во-вторых, это будет поводом ввернуть пассаж про важность, пользу или даже просто про существование базы знаний.

Как и во всем, здесь стоит знать меру. Однако не пренебрегайте информированием коллег о том, что происходит с вашей базой знаний.

Угрозы, вымогательства

Воруй любовь, убивай скуку

Писать сложнее, чем читать. Знаю это по себе, ведь эту статью я собирался написать еще два года назад. Поэтому для того, чтобы мотивировать людей не только читать, но и писать, придется заморочиться чуть больше. Что у нас есть в арсенале?

• Рассказывайте коллегам про угрозы отсутствия документации. Если ранее у вас никогда не было базы знаний, то начать стоит с самых основ, пусть даже вам они могут показаться очевидными.

  Расскажите про пресловутый bus factor и проиллюстрируйте примером, ведь наверняка вы с этим уже сталкивались на практике (надеюсь, впрочем, что не в такой трагичной форме).

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

• Не стоит, впрочем, слишком давить на страх, ведь это не лучший источник мотивации. Стоит также обратить внимание коллег на то, какие плюсы это несет для них.

  Надоело до одури заниматься одним и тем же? Если это в ваши силах, рассмотрите возможность ротации людей между проектами. Для этого, впрочем, нужно будет подготовить почву: документация, вводные лекции, право на безлимитные консультации.

  Хочется меньше запросов от техподдержки? Поделитесь с ними знаниями, так вас будут меньше дергать по пустякам. Как правило, техподдержка очень охотно и быстро впитывает все знания, что им предоставляют.

  Все вышесказанное звучит логично, но совсем нет времени на то, чтобы описывать детали текстом? Попросите провести лекцию и перенесите на вики самостоятельно в текстовом или хотя бы в видео формате. Почему-то на лекцию обычно соглашаются охотнее, чем на статью. Если знаниями обладает один-единственный человек, то даже такой формат будет лучше, чем ничего, хоть здесь и не обойдется без времязатрат с вашей стороны. В конечном итоге это позволит ознакомиться с областью и другим коллегам, в том числе и более благосклонным к ведению документации.

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

Играйте на здоровом самолюбии

Птицу кормом, а человека серебряной пулей обманывают

Мы, люди, любим, когда нас хвалят, ставят лайки, когда о нашем труде знают и когда мы видим, что наши старания не проходят даром. Давайте же используем это во благо!

• Добавьте блок новостей на главную страницу, где будет информация обо всех новых правках (или хотя бы обо всех новых статьях). Рядом с именем статьи непременно должен светиться ник автора правки.

• Если вам позволяют ресурсы, можно попробовать варианты геймификации и добавить рейтинги или ачивки (например, за N статей/правок). Хотя есть мнение, что эти штуки сработают далеко не в каждом коллективе.

• У меня не было столько времени, чтобы добавлять геймификацию, но я добавил блок "Your impact" на главную страницу. Там выводится 10 самых просматриваемых статей из числа отредактированных вами, а рядом с ними число просмотров с момента вашей первой правки.

  Идея эта не моя, я подсмотрел ее на MediaWiki хакатоне в Праге, где growth team рассказывали про свои исследования аналогичной фичи большой Википедии и предлагали поучаствовать в разработке. Конечно, мне пришлось переписать фичу с нуля, поскольку у меня совсем другие источники данных, чем у Wikipedia, но в остальном я старался следовать рекомендациям Growth team.

• Маленькое расширение Thanks может послужить аналогом лайков для конкретных правок. Оно, конечно, не очень удобное, но лучше, чем ничего. И реагируют коллеги на такие "спасибо" обычно очень положительно.

• Как я уже писал выше, не упускайте шанса похвалить ваших коллег, если они написали что-то крутое. Положительная обратная связь не будет лишней.

Расскажу, как я начал заниматься базой знаний. На заре моего трудоустройства коллега организовал мини-конкурс: автор наибольшего вклада в развитие вики должен был получить награду, достойную чемпиона стакан черной смородины (напомню, Veeam IT компания с достойными зарплатами, мы тут не голодаем). Смородина та кончилась пять-шесть лет назад, а проектом я занимаюсь и поныне. Не могу сказать, что это был гениальный ход с его стороны, но он сработал, а это главное.

Присматривайте за другими

У семи нянек детеныш без серебряной пули

Я искренне считаю, что для внутренней базы знаний любая форма премодерации это огромный могильный камень. Необходимость что-то с кем-то согласовывать убивает всяческое желание вносить правки. Тем не менее, без модерации вики быстро превратится в помойку с огромным количеством дублирующегося и устаревшего разрозненного контента, который еще и не так просто найти. Решение есть: постмодерация. Дайте людям писать как им удобно, а затем приведите написанное в порядок.

Постмодерацией (патрулированием правок) нужно заниматься заниматься регулярно, в идеале каждый день. Да, это отнимает время, но это необходимо, чтобы вики не превращалась в помойку. Расставляйте категории, чините навигацию, исправляйте нестандартное форматирование, чистите текст от пассивно-агрессивных нападок и явных ошибок.

Помимо того, что патрулирование правок позволяет сохранить организацию контента, это также помогает вовремя обнаружить, что у кого-то возникли проблемы или вопросы. Когда в ответ на твои безуспешные попытки сделать что-то хитрое с документацией тебе пишет ответственный за базу знаний; показывает и рассказывает, как проще всего сделать то, что тебе нужно, исправляет косяки и вообще ведет себя как душка, это подкупает. Я сталкивался с таким отношением на других вики-проектах, и мне это показалось самым рабочим методом обучения новичков. Теперь стараюсь продвигать те же принципы у нас.

Вместо заключения или "насильно мил не будешь"

Лучше на гривну убытку, чем на алтын стыда

Ваша база знаний подойдет не для всего и не всем. Даже в моем случае MediaWiki самая популярная и большая внутренняя база знаний, но далеко не единственная. Есть команды, привыкшие на прошлых местах работы к Confluence/Sharepoint/впишите нужное. Отдельные команды все еще бойкотируют создание внутренней документации под теми или иными поводами. На мой взгляд, это нормально.

Я продвигал вики, будучи джуном, и не имел возможности внедрить базу знаний в официальные процессы. Хотя это сказалось на скорости распространения и охвате, я все равно считаю, что в этом были свои плюсы. Если распространением знаний начинают заниматься по своей инициативе, это порождает куда более интересные и полезные результаты. К тому же отсутствие формализма и официоза позволит вам куда более гибко подходить к разработке и продвижению, писать ироничные дайджесты и полусерьезные посты на Хабр, да и вообще получать удовольствие от процесса.

Пожелание "сделайте так, чтобы мою вики использовали, пожалуйста" мало чем отличается от "сделайте так, чтобы в мою игру играло много человек". Да, у продвижения разных сервисов и услуг есть свои особенности, но у них гораздо больше общего, чем может показаться. Чтобы продвигать базу знаний, попробуйте мыслить как SMM специалист и основатель стартапа в одном лице, а не как Пётр I, насильно сбривающий бороды (никаких претензий к Петру, просто подход другой). И хотя идеального способа продвижения нет и вероятно, никогда не появится, в ваших силах найти рабочие для вашей конкретной компании способы. Удачи!

В рунете я почти не встречал материалов о том, как писать расширения для MediaWIki (платформы, на которой работает Википедия). Основной стартовой точкой при написании расширений был и остается официальный сайт платформы, но там процесс расписан не очень дружелюбно по отношению к новичкам. Попробуем же это исправить.

В этой статье я покажу, как написать простейшее расширение для Медиавики, включающее в себя новый метод API, расширение парсера и немного js/css для фронтенда. А чтобы не было скучно, приплетем сюда работу с Google Knowledge Graph.

Расширения MediaWiki

MediaWiki модульная платформа, куда можно устанавливать расширения для добавления самого разного функционала. Помимо того, что расширения могут реализовывать какой-то свой независимый функционал (например, добавлять какие-нибудь виджеты), оно также может и модифицировать функциональность платформы: например, менять принцип работы поиска или модифицировать внешний вид платформы. Посмотреть примеры расширений можно на официальном сайте платформы.

Пишутся расширения, как правило, на php+jQuery. Возможность встраиваться в код ядра MediaWiki (или в код других расширений) реализована через т.н. хуки. Хуки позволяют вызывать дополнительный код по заданным событиям. Примерами таких событий могут быть: сохранение страницы, вызов поиска по сайту, открытие страницы на редактирование и так далее.

Расширения MediaWiki позволяют делать что угодно: работать напрямую с базой, модифицировать вики-движок, работать с файловой системой и так далее. С одной стороны, это позволяет добавлять какой угодно функционал, но с другой накладывает на вас большую ответственность при установке новых сторонних расширений. Впрочем, довольно лирики, приступим к написанию своего расширения.

Что будем писать?

Готовое расширение можно взять тут:
https://github.com/Griboedow/GoogleKnowledgeGraph

Давайте развлечемся и напишем что-нибудь бесполезное. Скажем, расширение, которое будет вытаскивать описания с Google Knowledge Graph.

Т.е. расширение будет вот это:

Код этого приложения прост и изящен как <GoogleKnowledgeGraph query="Мэльхэнанвенанхытбельхын"/>

Превращать в это:

Штука довольно бесполезная, но она послужит хорошей иллюстрацией. Еще и с графом знаний Гугла поиграемся!

Расширение сделано исключительно в учебных целях, не рекомендую его использовать на настоящих вики. Гугл предоставляет 100 000 бесплатных запросов в день. Для небольших вики это не проблема, но на серьезных сайтах ресурс будет исчерпан очень быстро.

Как оно будет работать

Примерный принцип работы расширения выглядит так:

1. Пользователь сохраняет страницу, где в тексте присутствуют теги <GoogleKnowledgeGraph query="Ричард Докинз">.

   • MediaWIki позволяет использовать не только формат тега, но и формат функции парсера <link>: {{#GoogleKnowledgeGraph||query=Ричард Докинз}}.

2. Расширение функции парсера превращает тег в html код <span class="googleKnowledgeGraph">Ричард Докинз</span>

3. JS код при загрузке страницы идет по всем элементам .googleKnowledgeGraph и запрашивает через API нашего же расширения описания терминов, подставляя их в title.

4. API нашего расширения будет максимально примитивным: он будет передавать запросы от фронтенда на Google API, чистить ответ от всего лишнего и передавать очищенное описание сущности на фронт.

В целом, можно было бы обойтись и без фронтенда, но запросы на внешние сайты могут проходить не очень быстро. Лучше показать основной контент страницы пораньше, и в фоне догрузить необязательный контент. К тому же мы тут учимся, а не пишем серьезный код, верно?

Итого, нам потребуется:

1. Определить манифест нашего расширения.

2. Расширить MediaWIki API, добавив запрос на получение описания из Google Knowledge Graph

3. Расширить парсер MediaWiki, добавив обработку нового тега.

4. Добавить JS код, который будет выполняться по загрузке страницы

5. Подгрузить наше расширение в MediaWiki

6. Поделиться результатом наших трудов с сообществом.

А еще перед началом работы вам потребуется токен для работы с Google Knowledge Graph API. Сгенерировать его можно тут.

Создаем структуру расширения

Типичная иерархия файлов и папок для MediaWIki расширения выглядит так:

extensions                    <-- Папка всех расширений MediaWiki GoogleKnowledgeGraph      <-- Подпапка с нашим расширением      extension.json   <-- Манифест нашего расширения     i18n           <-- Каталог с используемыми строками для разных языков      en.json    <-- Строки на английском      qqq.json   <-- Описания строк для облегчения жизни переводчиков      ru.json    <-- Строки на русском     includes                             <-- PHP код      ApiGoogleKnowledgeGraph.php      <-- Расширение API      GoogleKnowledgeGraph.hooks.php   <-- Расширение парсера и другие хуки     modules                                <-- Папка с JS модулями          ext.GoogleKnowledgeGraph           <-- В нашем случае модуль только 1             ext.GoogleKnowledgeGraph.css   <-- CSS стили нашего модуля             ext.GoogleKnowledgeGraph.js    <-- JS код нашего модуля

Разберем содержимое всех файлов по порядку, и начнем с самого простого.

Интернационализация (i18n)

Для того, чтобы нашим расширением было удобно пользоваться на всех языках, можно воспользоваться стандартной системой интернационализации banana-i18n. Помимо облегчения интернационализации, эта система также позволяет хранить все тексты в одном месте (а не раскиданными по коду). Выглядит это примерно так:

qqq.json

{"@metadata": {"authors": [ "Developer Name" ]},"googleknowledgegraph-description": "Description of the extension, to be show in Special:Vesion.","apihelp-askgoogleknowledgegraph-summary" : "Help string for 'askgoogleknowledgegraph' API request","apihelp-askgoogleknowledgegraph-param-query": "Help string for 'query' parameter of API request 'askgoogleknowledgegraph'"}

en.json

{"@metadata": {"authors": [ "Nikolai Kochkin" ]},"googleknowledgegraph-description": "The extension gets brief description from Google Knowledge Graph","apihelp-askgoogleknowledgegraph-summary" : "API to get description from Google Knowledge Graph","apihelp-askgoogleknowledgegraph-param-query": "String to ask from Google Knowledge Graph"}

Создаем манифест расширения (extension.json)

Для начала разберемся, как нам сообщить MediaWiki, что нужно загрузить то или иное расширение. Путей на самом деле два:

• Использоватьrequire_once( '/path/to/file.php' ). Этот метод считается устаревшим, так что мы его подробно не будем рассматривать.

• Использовать функцию wfLoadExtension('ExtensionName'). Сейчас этот способ считается основным, так что на нем и остановимся. http://personeltest.ru/aways/habr.com/ru/company/veeam/blog/544534

Второй способ подразумевает наличие в папке файла extension.json с описанием манифеста приложения (как оно называется, из чего состоит, какие хуки использует и так далее).

Определяем манифест (файл extension.json):

{"name": "GoogleKnowledgeGraph","version": "0.1.0","author": ["Nikolai Kochkin"],"url": "http://personeltest.ru/aways/habr.com/ru/company/veeam/blog/544534/","descriptionmsg": "googleknowledgegraph-description","license-name": "GPL-2.0-or-later","type": "parserhook","requires": {"MediaWiki": ">= 1.29.0"},"MessagesDirs": {"GoogleKnowledgeGraph": ["i18n"]},"AutoloadClasses": {"GoogleKnowledgeGraphHooks": "includes/GoogleKnowledgeGraph.hooks.php","ApiAskGoogleKnowledgeGraph": "includes/ApiAskGoogleKnowledgeGraph.php"},"APIModules": {"askgoogleknowledgegraph": "ApiAskGoogleKnowledgeGraph"},"Hooks": {"OutputPageParserOutput": "GoogleKnowledgeGraphHooks::onBeforeHtmlAddedToOutput","ParserFirstCallInit": "GoogleKnowledgeGraphHooks::onParserSetup"},"ResourceFileModulePaths": {"localBasePath": "modules","remoteExtPath": "GoogleKnowledgeGraph/modules"},"ResourceModules": {"ext.GoogleKnowledgeGraph": {"localBasePath": "modules/ext.GoogleKnowledgeGraph","remoteExtPath": "GoogleKnowledgeGraph/modules/ext.GoogleKnowledgeGraph","scripts": ["ext.GoogleKnowledgeGraph.js"],"styles": ["ext.GoogleKnowledgeGraph.css"]}},"config": {"GoogleApiLanguage": {"value": "ru","path": false,"description": "In which language you want to get result from the Knowledge Graph","public": true},"GoogleApiToken": {"value": "","path": false,"description": "API token to be used with Google API","public": false}},"ConfigRegistry": {"GoogleKnowledgeGraph": "GlobalVarConfig::newInstance"},"manifest_version": 2}

Первая часть файла определяет то, что пользователь увидит в описании расширения на странице Special:Version

"name": "GoogleKnowledgeGraph","version": "0.1.0","author": ["Nikolai Kochkin"],"url": "http://personeltest.ru/aways/habr.com/ru/company/veeam/blog/544534/","descriptionmsg": "googleknowledgegraph-description","license-name": "GPL-2.0-or-later","type": "parserhook",

Далее мы указываем зависимости нашего расширения: с какими версиями MediaWIki расширение может работать, какие версии php требуются, какие расширения должны быть уже установлены и так далее.

"requires": {"MediaWiki": ">= 1.29.0"},

Затем мы указываем, где искать файлы со строками i18n

"MessagesDirs": {"GoogleKnowledgeGraph": ["i18n"]},

И сообщаем, в каких файлах искать классы для автоподгрузки. Подробнее тут.

"AutoloadClasses": {"GoogleKnowledgeGraphHooks": "includes/GoogleKnowledgeGraph.hooks.php","ApiAskGoogleKnowledgeGraph": "includes/ApiAskGoogleKnowledgeGraph.php"},

Заявляем, что мы реализовываем API метод askgoogleknowledgegraph в классе ApiAskGoogleKnowledgeGraph

"APIModules": {"askgoogleknowledgegraph": "ApiAskGoogleKnowledgeGraph"},

Перечисляем, какие коллбеки для каких хуков у нас реализованы

"Hooks": {"BeforePageDisplay": "GoogleKnowledgeGraphHooks::onBeforePageDisplay","ParserFirstCallInit": "GoogleKnowledgeGraphHooks::onParserSetup"},

Сообщаем, что модули наши лежат в папке modules

"ResourceFileModulePaths": {"localBasePath": "modules","remoteExtPath": "GoogleKnowledgeGraph/modules"},

И определяем наш фронтенд модуль с js и css. Когда модулей несколько, можно указать в коде зависимости между ними.

"ResourceModules": {"ext.GoogleKnowledgeGraph": {"localBasePath": "modules/ext.GoogleKnowledgeGraph","remoteExtPath": "GoogleKnowledgeGraph/modules/ext.GoogleKnowledgeGraph","scripts": ["ext.GoogleKnowledgeGraph.js"],"styles": ["ext.GoogleKnowledgeGraph.css"]}},

И, наконец, задаем дополнительные параметры конфигурации нашего расширения

"config": {"GoogleApiLanguage": {"value": "ru","path": false,"description": "In which language you want to get result from the Knowledge Graph","public": true},"GoogleApiToken": {"value": "","path": false,"description": "API token to be used with Google API","public": false}},"ConfigRegistry": {"GoogleKnowledgeGraph": "GlobalVarConfig::newInstance"},

В LocalSettings.php опции будут иметь стандартный префикс wg

$wgGoogleApiToken = 'your-google-token';$wgGoogleApiLanguage = 'ru';

И, наконец, задаем версию схемы манифеста

"manifest_version": 2

Мы используем лишь небольшой список поддерживаемых полей манифеста. Почитать обо всех полях можно тут.

Расширяем API

Для начала реализуем API.

В extension.json мы заявили, что у нас будет метод askgoogleknowledgegraph, реализованный в классе ApiAskGoogleKnowledgeGraph из файла includes/ApiAskGoogleKnowledgeGraph.php:

// extension.json fragment"AutoloadClasses": {    <...>    "ApiAskGoogleKnowledgeGraph": "includes/ApiAskGoogleKnowledgeGraph.php"},"APIModules": {           "askgoogleknowledgegraph": "ApiAskGoogleKnowledgeGraph"     },

Теперь реализуем наш метод. Файл includes/ApiAskGoogleKnowledgeGraph.php:

<?php/**  * Класс включает в себя реализацию и описание API метода askgoogleknowledgegraph * Для простоты я не реализую кеширование, любопытные могут подсмотреть реализацию тут:  * https://github.com/wikimedia/mediawiki-extensions-TextExtracts/blob/master/includes/ApiQueryExtracts.php */use MediaWiki\MediaWikiServices;class ApiAskGoogleKnowledgeGraph extends ApiBase {public function execute() {$params = $this->extractRequestParams();// query - обязательный параметр, так что $params['query'] всегда определен$description = ApiAskGoogleKnowledgeGraph::getGknDescription( $params['query'] );/** * Определяем результат для Get запроса.  * На самом деле Post запрос отработает с тем же успехом,  * если специально не отслеживать тип запроса \_()_/. */$this->getResult()->addValue( null, "description", $description );}/**  * Список поддерживаемых параметров метода */public function getAllowedParams() {return ['query' => [ApiBase::PARAM_TYPE => 'string',ApiBase::PARAM_REQUIRED => true,]];}/** * Получаем данные из Google Knowledge Graph,      * предполагая, что самый первый результат и есть верный. */private static function getGknDescription( $query ) {/** * Вытаскиваем параметры языка и токен. * Все параметры в LocalSettings.php имеют префикс wg, например: wgGoogleApiToken. * Здесь же мы их указываем без префикса */$config = MediaWikiServices::getInstance()->getConfigFactory()->makeConfig( 'GoogleKnowledgeGraph' );$gkgToken = $config->get( 'GoogleApiToken' );$gkgLang = $config->get( 'GoogleApiLanguage' );$service_url = 'https://kgsearch.googleapis.com/v1/entities:search';$params = ['query' => $query ,'limit' => 1,'languages' => $gkgLang,'indent' => TRUE,'key' => $gkgToken,];$url = $service_url . '?' . http_build_query( $params );$ch = curl_init();curl_setopt( $ch, CURLOPT_URL, $url) ;curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );$response = json_decode( curl_exec( $ch ), true );curl_close( $ch );if( count( $response['itemListElement'] ) == 0 ){return "Nothing found by your request \"$query\"";}if( !isset( $response['itemListElement'][0]['result'] ) ){return "Unknown GKG result format for request \"$query\"";}if( !isset($response['itemListElement'][0]['result']['detailedDescription'] ) ){return "detailedDescription was not provided by GKG for request \"$query\"";}if( !isset( $response['itemListElement'][0]['result']['detailedDescription']['articleBody'] ) ){return "articleBody was not provided by GKG for request \"$query\"";}return $response['itemListElement'][0]['result']['detailedDescription']['articleBody'];}}

Теперь мы можем обращаться по апи к нашей вики:

Get /api.php?action=askgoogleknowledgegraph&query=Выхухоль&format=jsonResponse body:{"description": "Выхухоль, или русская выхухоль, или хохуля,  вид млекопитающих отряда насекомоядных из трибы Desmanini подсемейства Talpinae семейства кротовых. Один из двух видов трибы; вторым видом является пиренейская выхухоль."}

Расширяем парсер и используем прочие хуки

// Фрагмент файла extension.json"AutoloadClasses": {"GoogleKnowledgeGraphHooks": "includes/GoogleKnowledgeGraph.hooks.php",<...>},"Hooks": {"BeforePageDisplay": "GoogleKnowledgeGraphHooks::onBeforePageDisplay","ParserFirstCallInit": "GoogleKnowledgeGraphHooks::onParserSetup"},

В extension.json мы заявили, что в классе GoogleKnowledgeGraphHooks из файла includes/GoogleKnowledgeGraph.hooks.php реализуем расширения для хуков:

• OutputPageParserOutput в методе onBeforeHtmlAddedToOutput;

• ParserFirstCallInit в методе onParserSetup

Немножко про используемые хуки:

• OutputPageParserOutput позволяет выполнить какой-то код после того, как парсер закончил формировать html, но перед тем, как html был добавлен к аутпуту. Здесь мы, например, можем подгрузить фронтенд. Фронтенд мы целиком расположили в модуле ext.GoogleKnowledgeGraph, так что достаточно будет подгрузить его.

• ParserFirstCallInit позволяет расширить парсер дополнительными методами. Мы добавим в парсер обработку тега <GoogleKnowledgeGraph>.

Итак, реализация (файл includes/GoogleKnowledgeGraph.hooks.php):

<?php/** * Хуки расширения GoogleKnowledgeGraph  */class GoogleKnowledgeGraphHooks {/** * Сработает хук после окончания работы парсера, но перед выводом html.  * Детали тут: https://www.mediawiki.org/wiki/Manual:Hooks/OutputPageParserOutput */public static function onBeforeHtmlAddedToOutput( OutputPage &$out, ParserOutput $parserOutput ) {// Добавляем подгрузку модуля фронтенда для всех страниц, его определение ищи в extension.json$out->addModules( 'ext.GoogleKnowledgeGraph' );return true;}/** * Расширяем парсер, добавляя обработку тега <GoogleKnowledgeGraphHooks> */public static function onParserSetup( Parser $parser ) {$parser->setHook( 'GoogleKnowledgeGraph', 'GoogleKnowledgeGraphHooks::processGoogleKnowledgeGraphTag' );return true;}/** * Реализация обработки тега <GoogleKnowledgeGraph>  */public static function processGoogleKnowledgeGraphTag( $input, array $args, Parser $parser, PPFrame $frame ) {// Парсим аргументы, переданные в формате <GoogleKnowledgeGraph arg1="val1" arg2="val2" ...> if( isset( $args['query'] ) ){$query = $args['query'];}else{// В тег не был передан аргумент query, так что и выводить нам нечегоreturn '';}return '<span class="googleKnowledgeGraph">' . htmlspecialchars( $query ) . '</span>';}}

Добавляем фронтенд

Фронтенд свяжет воедино все, что мы реализовали выше.

// Фрагмент файла extension.json    "ResourceModules": {"ext.GoogleKnowledgeGraph": {"localBasePath": "modules","remoteExtPath": "GoogleKnowledgeGraph/modules","scripts": ["ext.GoogleKnowledgeGraph.js"],"styles": ["ext.GoogleKnowledgeGraph.css"],"dependencies": []}},  "ResourceFileModulePaths": {"localBasePath": "modules","remoteExtPath": "GoogleKnowledgeGraph/modules"},

В extension.json мы заявили, что у нас есть один модуль ext.GoogleKnowledgeGraph, который находится в папке modules и состоит из двух файлов:

• modules/ext.GoogleKnowledgeGraph/ext.GoogleKnowledgeGraph.js

• modules/ext.GoogleKnowledgeGraph/ext.GoogleKnowledgeGraph.css

Загрузку модуля мы реализовали чуть раньше в методе onBeforeHtmlAddedToOutput. Определим теперь и сам код модуля.

Для начала зададим стили
(файл modules/ext.GoogleKnowledgeGraph/ext.GoogleKnowledgeGraph.css):

.googleKnowledgeGraph{    border-bottom: 1px dotted #000;    text-decoration: none;}

А теперь возьмемся за JS
(файл modules/ext.GoogleKnowledgeGraph/ext.GoogleKnowledgeGraph.js):

( function ( mw, $ ) {  /**   * Ищем все элементы с <span class="googleKnowledgeGraph">MyText</span>,   * вытаскиваем MyText и отправляем запрос   * /api.php?action=askgoogleknowledgegraph&query=MyText   * После чего добавляем результат в 'title'.   */$( ".googleKnowledgeGraph" ).each( function( index, element ) {$.ajax({type: "GET", url: mw.util.wikiScript( 'api' ),data: { action: 'askgoogleknowledgegraph', query: $( element ).text(),format: 'json',},dataType: 'json',success: function( jsondata ){$( element ).prop( 'title', jsondata.description );}});});}( mediaWiki, jQuery ) );

JS код довольно прост. jQuery нам достался даром, поскольку MediaWiki подгружает его автоматически.

Подгружаем наше расширение и радуемся

Для загрузки расширения, как мы уже обсуждали, потребуется поправить файл LocalSettings.php. Добавляем в самый конец:

// Фрагмент файла LocalSettings.php<?php<...>  wfLoadExtension( 'GoogleKnowledgeGraph' );$wgGoogleApiToken = "your-google-token";$wgGoogleApiLanguage = 'ru';

Можно пробовать! Добавим на страницу что-нибудь эдакое:

Даже <GoogleKnowledgeGraph query="прикольный флот"/> может стать отстойным.

И получим:

Делимся с сообществом

Если есть возможность поделиться расширением с общественностью, то можно создать страницу на MediaWiki с кратким описанием, что ваше расширение может сделать (не забудьте скриншоты: лучше один раз увидеть, чем сто раз прочитать). На страницы с описаниями расширений обычно добавляют шаблон Extension, поля которого хорошо задокументированы. Если же возникнут сложности, всегда можно скопировать его с другой страницы расширений и подправить отличающиеся поля.

Заключение

В статье был описан случай довольно простого расширения, но, на самом деле, такие расширения как iFrame, CategoryTree, Drawio и многие другие не очень далеко ушли по сложности.

За скобками остались такие вещи, как работа с базой, кэширование, OOUI и много-многое другое. Все ж я вас не напугать хотел, а как раз наоборот показать, что писать расширения под вики на самом деле совсем не сложно и не страшно.

Ссылки

• Код расширения целиком на github

• Страница расширения на MediaWiki

• Страница помощи разработчику расширений MediaWIki

• Example extension расширение с пачкой примеров на все случаи жизни

• Документация MediaWiki кода

• banana-i18n (как работает интернационализация)

• Схема extension.json (файл поддерживает много дополнительных полей)

Привет! Я Илья Тананаев. Руковожу отделом первой линии техподдержки в ITSumma. И хочу поделиться опытом, как из поиска решения проблемы пропущенных чатиков с клиентами мы построили кузницу кадров. Успешно успевая при этом обрабатывать 3k+ клиентских обращений в сутки.

Итак, пару лет назад мы столкнулись с обычной проблемой: админы техподдержки оказались не настолько мультизадачными, чтобы успевать тушить все пожары, решать текущие проблемы и при этом следить за миллионом чатиков с клиентами.

Придумали простое и утилитарное решение поставить между высококвалифицированными админами и клиентами первую линию поддержки, которая взяла бы на себя относительно простую работу по уточнению запросов. Но дальше случилось так, что бонусом к изначальной задаче мы открыли отличный способ развития компании и путь обучения недавно пришедших в IT специалистов.

И в этой статье расскажу, что из нашего опыта вы можете применить у себя в любой компании, чтобы справиться с дефицитом кадров.

С чего всё началось

ITSumma начиналась с того, что мы помогали сайтам выдерживать нагрузки и не падать при любых обстоятельствах. Сейчас, спустя 13 лет после основания компании, техподдержка уже далеко не единственное направление нашей работы, но по-прежнему существенное. У нас большой отдел эксплуатации, который следит за инфраструктурой клиентов и реагирует на инциденты 24/7 с SLA в 15 минут.

Когда клиентов было не очень много, дежурные админы сами реагировали не только на алерты мониторинга, но и на все обращения клиентов, включая телефонные звонки. В маленькой команде это кажется оптимальным вариантом зачем заводить сломанный телефон, если исполнитель сам может принять задачу и лучше, чем кто бы то ни было, уточнить детали. Но постепенно компания росла, клиентов становилось больше... и в 2018 году система стала давать сбои.

С ростом числа клиентов дежурным админам стало слишком тяжело одновременно решать свои обычные рабочие задачи и отвечать на запросы клиентов; начали появляться потерянные или неотвеченные клиентскиечатики. Мы поняли, что пора разделить контроль за отслеживанием входящих запросов и задач и, собственно, их исполнение.

Зачастую любой контроль ложится на плечи руководителя, но такая рутина, как принять задачу у клиента и передать её дальше не лучшее использование времени и сил менеджера. Эффективнее потратить их на более важные и подходящие по скиллам дела, а рутину делегировать отдельным специальным людям.

Так появилась первая линия поддержки.Вначале она состояла всего из... двух человек. Они должны были звонить и принимать звонки от клиентов, следить за всеми входящими обращениями и облекать их в задачи для админов. Плюс, что-то совсем простое делать сами и потихоньку обучаться новому.

Итерации решения

Сначала первая линия не работала 24/7, да и в принципе, не сразу взяла на себя работу с вообще всеми клиентами. Тем не менее, когда мы вышли на две стабильные смены с 7 утра по Москве (с 12 по Иркутску наш стандартный режим для большинства сотрудников) и с 11 по Москве в будние дни, это уже сильно сняло нагрузку с админов и помогло упорядочить работу. Мы поняли, что первая линия действительно полезна, а от админов круглосуточной техподдержки поступил запрос на работу первой линии не только в дневное время.

В 2019-м мы ввели еще смены для подстраховки на время пиковой нагрузки по будням с 10 утра по Москве. А позже, проанализировав ситуацию, решили, что нужно переводить первую линию на 24/7 чтобы помогать техподдержке всё время.

Итоги первого года работы первой линии:

• Избавили квалифицированных админов от рутины по звонкам и приёму обращений клиентов, сделав их работу более упорядоченной.

• Ответственным за SLA стал не только отдел эксплуатации, но и первая линия поддержки.

• Получили более надежный процесс обслуживания клиентов, в котором задачи не теряются, а выполняются вовремя.

• Сотрудники первой линии начали не просто передавать задачи и создавать таски, но и самостоятельно выполнять некоторые из них, например, обновлять сертификаты. Чем помогли админам эффективнее использовать свои ресурсы.

• Высвободили часть ценного времени ведущих админов, тем самым получив ресурс для роста компании.

Постепенно на первую линии перешло реагирование на некоторые алерты мониторинга, обновление сертификатов, редактирование конфигурации nginx и ssl certbot. Например, если у клиента в ночное время приходил алерт по продовой площадке и не резолвился, то нужно было оповестить клиента в течении 15 мин согласно SLA.

На картинке число обращений по одному их проектов, которое ежемесячно обрабатывают самостоятельно бойцы первой линии. Понятно, что сложность у них разная, но объёмы всё равно можно представить. Дополнительно мы строим еще кучу графиков в Redash по дням недели, по часам и т.д., чтобы распределять дежурства, соответствующие нагрузке.

Расписание для людей

Проблема приема обращений решилась, но с учётом перехода на круглосуточный режим надо было утрясти расписание работы сотрудников. Если смены просто зафиксировать, условно два через два, то в разные месяцы получится разное количество смен и люди будут то перерабатывать, то не дорабатывать (по ТК должно быть определенное количество часов за период).

Казалось бы, задача сменного расписания довольно типовая и уже точно должно быть выработано нормальное решение. Но нам все равно пришлось попробовать разные варианты на собственном опыте, чтобы в итоге не страдало здоровье наших коллег и никто не выгорал.

Мы попробовали разные варианты: 8- и 12-часовые смены, только дневные и только ночные, вперемешку и т.д. Вот что получилось:

• Думали было над 12-часовыми сменами вперемежку день/ночь но даже не стали пробовать на практике: поразмыслив, поняли, что это был бы жестокий удар по биоритму и здоровью.

• Пробовали чередовать 8-часовые вечерние и ночные смены, чтобы разброс был не такой большой, ритм нарушается все равно. В итоге люди не могут отоспаться и отдохнуть и просто неожиданно заболевают.

• Отдельно ночные и дневные дежурные вариант, которые устроил больше всего.

Дополнительно по мере развития отдела появились еще 8-ми часовые смены на дневное пиковое время в это время нагрузка самая большая, и 12 часов подряд её выдерживать тяжело. Сейчас у специалиста первой линии есть не только возможность выбрать подходящий ему график, но и расставить приоритеты для возможной ротации, как по времени, так и по отделам. Сотрудник оценивает по 5-балльной шкале удобство возможного времени работы, а также оставляет комментарии о том, какие у него предпочтения, либо внерабочая активность.

Развитие специалистов первой линии поддержки

Как я уже сказал, изначально первая линия поддержки появилась, чтобы переложить часть нагрузки с плеч высококвалифицированных специалистов на менее опытных коллег. Поэтому в целом мы не выставляем высоких требований к навыкам сотрудника первой линии: важно понимание работы веба и основ сервисов, ну и желание развиваться в администрировании. Но на разных этапах и в зависимости от потока кандидатов мы берём более подготовленных людей или акцентируем внимание на софт-скиллах.

Однако быстро выяснилось, что чем опытнее специалист первой линии, тем больше времени экономится на следующих этапах и быстрее решаются проблемы клиентов. Так в наших глазах (и в глазах наших сотрудников) работа в поддержке превратилась из обычной рутинной в трамплин для развития в IT. Поработав на передовой, ребята набираются опыта, растут как специалисты и переходят в другие отделы на более высокие должности.

Но это нам теперь понятно, что развитие выгодно и сотрудникам, и нам, как компании. А началось все очень прозаично и прагматично.

Таско-дни или командировки в другие отделы

На какой-то из переходных стадий формирования режима работы для комфортной работы нам не хватало по сути дела полставки. Мы взяли в штат нового сотрудника на полную ставку, а суммарное лишнее время решили попытаться использовать с пользой.

Договорились с соседними отделами мониторинга и документации, что будем отправлять к ним людей на таско-дни в эти один-три дня сотрудники первой линии будут полностью заниматься задачами по документации или мониторингу, как будто они работают в этих отделах.

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

Дело в том, что сотрудники нашей первой линии создают задачи для мониторинга, но им не всегда понятно, почему регламент описания задачи именно такой, почему должны быть прописаны определенные параметры сервера, какой процесс проходит задача дальше и т.д. А когда человек попадает на ту сторону и получает на исполнение составленную его же коллегой задачу, в которой не хватает информации, он сразу начинает понимать, почему и какие нюансы надо уточнять. Это помогает впоследствии гораздо лучше выполнять регулярную работу в первой линии становится больше осознанности.

Эксперимент с таско-днями был удачным. Он наглядно показал пользу от выбранной тактики помогать развиваться нашим сотрудникам. Поэтому теперь мы всегда закладываем резерв под подобную практику, но сейчас это не несколько дней для нескольких человек, а полноценные две недели или, в последнее время, месяц для одного сотрудника первой линии, которые он работает в другом отделе. Мы называем это командировками.

Наши командировки похожи на стажировку, только лучше. За время месячной командировки человек успевает не только повысить свою квалификацию, но и принести пользу отделу, к которому он прикомандирован. В отличие от стажировки, на которую приходят совсем с нуля, сотрудник первой линии уже знаком с процессами в компании и быстрее входит в курс дела. У него есть мотивация на рост. И возможность понять, что ему ближе и как он хочет дальше развиваться.

К тому же, есть пространство для манёвра. По результатам командировки, если навыков еще недостаточно, можно спокойно вернуться в первую линию и там подрасти в выбранном направлении во время относительно малой загруженности браться за задачи для саморазвития под контролем более опытных коллег. В случае же испытательного срока или стажировки приходится расставаться, если отведенного времени не хватило.

На текущий момент командировка это привилегия. Надо отработать хотя бы несколько месяцев в первой линии и заслужить доверие. Кандидатам мы подробно объясняем, чем занимаются отделы, с чем придется столкнуться, работая там, и какие навыки можно получить в результате. А потом спрашиваем, в чем сотруднику интереснее себя попробовать, и, учитывая его скиллы и потребности отделов, отправляем в командировку.

Направления для командирования сотрудников первой линии поддержки такие:

• документация;

• мониторинг;

• эксплуатация;

• дежурства второй линии;

• аккаунтинг;

• и даже разработка.

В некоторых случаях это самый короткий и эффективный путь для расширения отделов. Например, командировки сильно помогают расти отделу документации. Часто люди не понимают, чем занимаются техписы и что там действительно необходимы технические навыки у нас в отделе документации пользуются консолью, сами уточняют детали в логах и собирают схемы с систем мониторинга.

Это нас возвращает к тому, зачем понадобилось автоматизировать обучение. Компания быстро развивается, есть много возможностей для роста, и в итоге достаточно часто на первую линию нужны новички (не путать с текучкой, её у нас как раз нет). Так настройка системы обучения и knowledge sharing превратились в приоритетные задачи.

Онбординг-курсы

В технической поддержке много составляющих, которые взаимодействуют со всеми системами: мониторингом, таск-трекером, вики и т.д. Специалисту на первой линии нужно хорошо ориентироваться в потоке и уметь быстро находить нужную информацию. Систематизация знаний и работа над документацией необходимый этап.

Документирование нашей работы прошло довольно стандартный путь:

• Понятно, что сначала документации как таковой не было были разрозненные наброски.

• На первой итерации по улучшению я выделил время и постарался её систематизировать стало чуть лучше, но еще не достаточно.

• Вторая итерация была результатом того, что у нас уже появилось свободные полставки, но мы еще не ввели таско-дни. Наша коллега несколько недель приводила в порядок документацию, после чего по этой документации новый сотрудник уже мог сам более-менее разобраться, что да как.

• Третья итерация не конечная точка, а непрерывная работа по улучшению. Мы собираем отзывы новичков, исправляем и расширяем то, где обнаруживаются недостаточно понятные места. Вообще фидбэк новичков очень полезен, а когда они еще и дописывают недостающую информацию, это вообще супер.

Однако, когда найм стал еще более активным, просто документации для онбординга стало не хватать. Документация, в любом случае, древовидная, и когда ты только погружаешься, разбираться в ней не очень удобно. Сразу трудно сориентироваться, что нужно запомнить в первую очередь, а что лучше изучить на примерах, когда уже столкнешься с этим в работе.

Еще несколько месяцев назад, чтобы ввести в курс нового коллегу, кому-то из менеджеров или более опытных сотрудников приходилось ртом рассказывать всё самое важное, знакомить с основными инструментами, сидеть рядом и показывать, что нужно сделать в каждом случае. Это два-три полных дня и еще пару недель регулярных индивидуальных консультаций долго и трудозатратно.

Для автоматизации процесса онбординга поднялиMoodle и сделали свои курсы. Они состоят из некоторой справочной информации, видеоуроков и тестов. У роликов есть временне метки с описаниями, поэтому к такому материалу удобно возвращаться, если позже понадобится что-то уточнить.

Помимо видео, в Moodle удобно делать тестирование. Причем, тестирование нам нужно, не чтобы оценить сотрудника, а чтобы еще раз акцентировать внимание на самых критически важных моментах как вопросы для самопроверки.

При проверке скрипта на корректность перед запуском на какие критерии обращаем внимание?

1. block for commit.

2. block for delay.

3. PS/SQL file successfully completed.

4. exit.

5. set auto commit off.

6. current schema.

В тест мы вынесли то, что, по нашему опыту, чаще оставалось не до конца понятным. Тестирование круто вскрывает нюансы и снижает число будущих косяков.

Пройти и курс, и тест можно пройти сколько угодно раз, это ни на что не влияет.

Можем ли мы изменять категорию задач вручную в созданной задаче? Если да, то где?

a. Можем, но аккуратно в Состояние.

b. Нет

c. Можем. В созданной задаче в правой колонке. Там, где Категория

d. Неее. Такого быть не может

e. Надо зайти в группы слева и там найти логово дракона. Вскрыть яйцо и после откроется тайна, где можно изменить категорию у задачи.

Как видите, это не похоже на строгую сертификацию. Это просто еще один способ помочь новому сотруднику усвоить много информации в короткие сроки.

После доработки документации онбординг курсы это лучшие инвестиции в развитие отдела.

Потратив один раз время и вложившись в автоматизацию стартового обучения, мы:

• Сэкономили время опытных специалистов на онбординг новичков.

• Уберегли главного наставника новичков от выгорания.

• Сделали онбординг качественнее (и это, пожалуй, главное). Когда один и тот же человек пятый-десятый раз рассказывает одно и то же, он легко может что-то пропустить, потому что путается, что кому уже рассказывал. С автоматическими курсами такое не произойдет.

И проверять, что человек точно всё понял и готов к боевой работе, с курсами гораздо проще и объективнее. Вообще, результат так всем понравился, что мы уже сделали обучение для отделов документации и мониторинга именно туда чаще всего вырастают из первой линии поддержки.

Результаты

Мы начинали первую линии поддержки с совершенно утилитарной целью и не ожидали, что построим службу, которая приносит компании гора-а-а-аздо больше пользы, чем зафиксировать обращение, передать на решение.

Для сотрудников это хорошая возможность для старта карьеры: начальные требования очень лояльные и есть, куда расти. ITSumma занимается разными направлениями, так что новичок у нас может попробовать себя в разных областях и выбрать, что ему по душе. При этом мы расширяемся, поэтому способные люди точно не останутся без новых вызовов и повышения.

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

Сейчас в первой линии работает 13 человек, из них 4-5 постоянно находятся в командировках в бэк-отделах, получают новые знания и повышают имеющиеся. За время этого не очень-то длинного эксперимента уже 9 человек пошли на повышение. Например, первая линии поддержки была отправной точкой для тимлида отдела дежурств и тимлида отдела документации, специалистов в отделах документации, мониторинга, бэкапов и аккаунтинга.

И да, у нас больше нет проблем с пропущенными обращениями или невыполненными вовремя задачами от клиентов. Админы и дежурные не отвлекаются на звонки, а расходуют свои скиллы для решения сложных инфраструктурных задач.

Takeaways

В условиях дефицита опытных специалистов на рынке IT-компании в любом случае вынуждены выращивать кадры. Если этот процесс у вас еще не отлажен, но в вашей компании больше 20 человек, найдите участок, в котором можно приносить пользу с малыми знаниями, и сделайте из этого собственную кузницу.

Первая линия поддержки это просто пример. У любой IT-компании есть что-то, что могут делать новички: ручное тестирование, простая верстка, документация, скриптованное бэкапирование или обновление. Всегда можно найти подходящую песочницу.

Чтобы выращивание специалистов приносило пользу, а не боль, придется вложиться в документацию и онбординг. Но документация и налаженный процесс информирования об обновлениях нужен в любом случае и для новых коллег с опытом, и для старых после отпуска. А порядок в онбординге и создание материалы для новых сотрудников поможет вашей компании расти и развиваться, так что это инвестиции в своё будущее.

Напоследок признаюсь, что были некоторые внутренние опасения, когда (уже больше года назад) мы перешли на удалённый режим работы и начали активно нанимать людей не из Иркутска, Москвы и Питера то есть городов нашего оффлайнового присутствия на момент коронавирусного перелома. Но опасались зря: у нас уже работает достаточно людей из ранее непривычных часовых поясов, и вообще,вакансии в отделе практически постоянно есть. В общем, разница во времени не помеха, если люди хотят работать, а мы хотим, чтобы они у нас работали.

Пост о том, зачем и как аккуратно вести проектную документацию, даже если у вас Agile. Делюсь перечнем и структурой полезных документов и рекомендациями по работе с ними.

Речь пойдет в основном о внутренних документах, которые обычно никто не просит писать, но которые на самом деле нужны команде.

Небольшое лирическое отступление про то, что меня вдохновило на написание этого текста:

При разработке ИТ-систем мне кажется очень важным поддерживать порядок в документации. Это и есть та самая стена, на фоне которой разворачивается проектная жизнь - на нее смотрят и делают выводы, что это за проект и как там все работает.

Зачем писать

Бывают проекты и без документации - но скорее всего так получилось не от хорошей жизни, либо никто из участников не знает, что так можно было.

Обоснованность наличия документации - отдельная тема, об этом писали, например, здесь.

Если коротко - то без бумажки ты букашка. Наша память обманчива и недолговечна. Завтрашний ты обманешь себя сегодняшнего или наоборот. Придет новый человек или уйдет старый - каждый такой финт будет стоить вам дорого. Без общей картины вы будете заниматься микроменеджментом и разработкой того, что уже кем-то сделано, но он забыл вам об этом сказать. Будете делать петли и вставлять друг другу палки в колеса. А через полгода мучительно вспоминать, зачем нужен этот огромный кусок кода, который все тормозит. И это даже не касаясь кейса, когда вы заказали разработку на стороне.

Что писать

Сложно представить проект, на котором документация не нужна совсем. Другой вопрос, что она может быть разного формата и в разных объемах, покрывать разные аспекты системы.

Например, на старте проекта с гибкой методологией велика вероятность, что все еще раз 5 поменяется до момента внедрения. Поэтому подробное техническое описание может быть лишней тратой времени. А вот позитивный сценарий - на какие кнопки в каком порядке пользователь нажимает, какие данные вводит - нужен всем членам команды. И при частых его изменениях особенно важно, чтобы у всех было единое понимание текущей версии процесса.

Легче кому-то одному потратить пару часов на документирование, чем всей команде постоянно проверять свою память.

То есть даже когда обстоятельства не в пользу полноценного описания системы и вы работаете в Agile-режиме - важно понимать, что какая-то документация существенно облегчит процесс разработки и принесет много пользы.

Как выбрать то, что нужно документировать - дело каждого проекта. Приведу структуру и состав документации, которые считаю полезными.

Необходимый минимум

На мой взгляд документы, которые важны практически на любом проекте, это:

1. Документ-маршрутизатор

   Место, откуда можно добраться до всех артефактов проекта. Это может быть страница в Confluence, пространство Notion или просто Google-документ. Важно создать единую точку входа - пусть там будут только ссылки на разные инструменты и источники, но вам не придется запоминать пути поиска нужного файла.

   

2. Артефакты проектных процессов

   Флоу процесса разработки, статусная модель задач, доски с беклогом, план-график проекта, список нужных контактов и пр. Наличие такой документации налаживает процесс работы и делает его более комфортным. А также сильно разгружает аналитика/менеджера/тимлида и всех, кого волнует выполнение задач и сроки.

   

3. Глоссарий

   Приводит всех участников работ к одному понятийному полю. Особенно полезен там, где много специальных терминов или разночтений. На некоторых проектах достаточно всего нескольких определений, но полезно все же их зафиксировать.

4. Артефакты бизнес-потребности и бизнес-процесса

   Agile-манифест гласит: Работающий продукт важнее исчерпывающей документации. Но нельзя разработать работающий как надо продукт без четкого понимания, что же мы все-таки делаем и зачем. Бизнес-требования, схема процесса или просто письмо с постановкой от заказчика - что-то должно быть.

   

5. Концептуальная модель системы

   Описание основных сущностей, верхнеуровневая функциональность и взаимодействие с другими системами.

   Используйте IDEF0, "дорожки" BPMN, просто схему или текстовый перечень - главное обозначить принцип работы вашей системы.

   Пример верхнеуровнего описания процесса

6. Классы пользователей и уровни доступа

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

7. Cценарии использования

   Даже если вы не используете этот инструмент для разработки требований - какой-то сценарий работы системы у вас есть. Это может быть инструкция для пользователей или тех. поддержки. Или последовательность вызовов с параметрами, если речь идет о взаимодействии систем.

8. Логика работы системы

   По коду или БД не всегда получается понять смысл функционала. Например, формула расчета стоимости скорее всего задается бизнес-правилами, о которых коду ничего не известно.

   Эти данные так или иначе передаются разработчикам при постановке задачи. Удобно сразу их записывать в виде читаемого документа, а в задачах вставлять только ссылки на место в этом документе. А если в тот же документ прикреплять тест-кейсы - будет совсем красиво.

   

9. Описание АПИ

   Да пребудет с нами swagger и стандартный формат ответа методов. Если с вами интегрируются внешние компании - не обойтись и без подробного описания параметров.

10. Тестовые данные

    Среды, учетные записи и все, что нужно, чтобы не сводить с ума тестировщика однообразными вопросами.

11. Ограничения/нефункциональные требования

    Вы договорились, что рассчитываете максимум на 100 пользователей? Делаете импорт справочников раз в сутки в час ночи? Внешняя система не умеет принимать какие-то значения? Сделайте приятно себе в будущем - запишите все эти детали.

Другие типы документов

Потребность в некоторых документах возникает вариативно, в зависимости от особенностей проекта:

1. Архитектура системы

   Иногда необходимо детальное описание сервисов и их взаимодействия. Например, если сервисов несколько и они взаимосвязаны, или если архитектура микросервисная.

2. Требования к данным

   Логическая модель, требования к составу и формату данных, особенности работы с ними и пр. Всё это не всегда покрывается характеристиками БД - в таком случае полезно зафиксировать их в отдельном документе.

   Сюда же можно добавить соглашения о формате БД - принципы наименования таблиц и атрибутов, используемые типы данных и пр.

3. UX/UI макеты и прототипы

   Их лучше сразу собирать в одном известном всем месте и держать в актуальном состоянии.

   С чехардой в макетах разбираться потом очень сложно. Просто представьте, что у вас хотя бы 3 экрана и у каждого хотя бы по 5 состояний. И аналитик, дизайнер и разработчики смотрят каждый в свой проект в фигме.

   

4. Описание интеграций

   Протоколы интеграций, спецификации АПИ, процессы и потоки данных и всё, что необходимо для избежания недоразумений при взаимодействии с другими системами.

   

5. Безопасность

   В целом параметры безопасности могут быть описаны вместе с доступами или нефункциональными требованиями, либо же наследоваться от общего контура ИТ компании. Но бывают системы с приоритетом или особым подходом к этой характеристике.

6. Внешняя документация

   Документы для пользователей, партнеров, надзорных органов и прочие артефакты, которыми система общается с внешним миром.

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

Как писать

Несколько инсайтов о работе с документацией:

• Не забывайте про актуальность

  Стоит писать только ту документацию, которую вы сможете поддерживать в актуальном состоянии.

  При отсутствии описания люди начнут общаться друг с другом и у них есть шанс добраться до истины. При неактуальной документации - все будут на нее смотреть и делать неправильно.

  

• Неоформленные артефакты - тоже документация

  Удобно складывать в одно место те артефакты, которые нет возможности обработать и хорошо оформить.

  Например, письма с договоренностями, примеры данных, ссылки и пр. Иначе вы скорее всего просто забудете, что такое когда-то было. Ну и в случае, если вдруг потребуется подтвердить какое-то согласование - не придется тратить час на поиск нужного письма в почтовом клиенте.

• Растите культуру документирования в команде

  Не обязательно всё должен документировать один человек, особенно если в команде нет специальной роли для этого. Даже не технические писатели умеют складывать ссылки в нужное место, писать чек-листы, комментировать макеты и прочее.

  Важно договориться, как такая документация будет поддерживаться.

  

• Комментарии в коде не всегда спасают

  Структура кода не обязана повторять структуру процесса/функционала и, тем более, бизнес- и пользовательских требований. Поэтому из кода можно понять "как" работает система, но на вопросы "зачем?", "почему?" и "как должна?" отвечает именно проектная документация.

• Планируйте и декомпозируйте работу с документацией

  Документирование - это задача, которую легко разбить на небольшие отрезки времени и размазать по спринту.

  Когда-то я бронировала в календаре последние 2 часа пятницы на составление/актуализацию документации. Принимать решения в это время опасно, к тому же эта деятельность помогает подвести итоги рабочей недели и запланировать следующую.

• Закрывайте техдолг

  При введении функционала в эксплуатацию важно выделить время на дооформление хвостов. Иначе не видать спокойной поддержки и доработки системы.

  Понять, чего не хватает, просто: представьте, что вы приходите на этот проект сейчас, и никто из предыдущей команды с вами поговорить не может.

  

• Больше схем и диаграмм

  Визуальная информация воспринимается легче и быстрее, лучше запоминается. Чем больше данных вы представите графически - тем доступнее и короче будет документация.

  Поможет изучение графических нотаций и UML, практика их применения, а также замечательная книга "Говори на языке диаграмм".

• Учитесь писать нехудожественные тексты

  Навык написания текстов сильно ускоряет процесс документирования и повышает его качество. Рекомендую использовать https://glvrd.ru. Плюс по возможности почитать "Пиши, сокращай" и "Бизнес-копирайтинг". Так и работа быстрее пойдет, и тексты станут понятнее и приятнее.

  Вот еще хороший доклад на тему "Как писать полезные технические тексты".

Как итог

Не обязательно подробно документировать всё, или хотя бы выполнять "необходимый минимум" из этой статьи. Всегда полезно сверять часы с реальностью и понимать - что действительно нужно и поможет достичь цели.

Но важно знать, какие есть инструменты и практики и как это делают в идеальном мире. Тогда вы поймете, на чем основывать свою работу, чтобы не изобретать велосипед и не напарываться на издревле известные грабли.

Даже если у вас нет ТЗ с тезаурусом и перечнем иллюстраций - структурированное и понятное хранение имеющейся документации облегчит жизнь всей команды. А также сподвигнет вас и коллег более собранно и ответственно относиться к проекту.

В последние несколько лет в среде технических писателей все больше на слуху концепция Docs as Code. Если вы раньше не сталкивались с этим термином, он обозначает подход к разработке технической документации с использованием тех же инструментов и процессов, что и написание кода. Если DocOps это про процессы и коллаборацию, то Docs as Code про инструментарий, при помощи которого мы несмотря ни на что. Мы выбрали этот подход, когда создавали портал документации Plesk.

В этой статье я кратко расскажу, что такое Docs as Code и зачем оно нужно, а затем дам несколько советов относительно того, как это чудо враждебной техники внедрять, сдобрив всю историю рассказами о тех граблях, на которые мы наступили, топая в светлое будущее. Я старался писать такую статью, которая пригодилась бы мне в 2017 году, когда мы эту кашу заваривали.

(N.B. Сразу оговорюсь, что эта статья - обзорная, в ней нет огрызков конфигов или примеров кода. Если вы уже знаете теорию и ищете, как конкретно пропатчить KDE2 под FreeBSD, статья может быть вам не очень интересна).

Акт 1: Теория

Давным-давно, в далёкой-далёкой галактике

Начнем от противного. Чтобы лучше понять преимущества Docs as Code, посмотрим, как документацию писали (а много где и продолжают писать) мои коллеги в компаниях по всему миру. Как правило, выглядит это так:

• Документацию пишут и поддерживают технические писатели и только они.

• Для разработки и публикации используются специализированные проприетарные инструменты, такие как MadCap Flare, Adobe RoboHelp, или Author-it. Реже Wiki или Confluence.

• Технические писатели работают обособленно. Что происходит у них в отделе, никто в конторе не знает и особо этим не интересуется. Взаимодействие на уровне "разработчик заметил ошибку в примере кода и завел баг в Jira", так как с инструментами технических писателей разработчик не знаком и доступа туда, где хранятся доки, у него нет.

Окей, в чем недостатки status quo? Их несколько:

• Отсутствие интереса к документации у большинства сотрудников. Хороша документация разрабатываемых продуктов или плоха никто не знает, и никому до этого нет дела. Не мой цирк, не мои обезьяны.

• Плохая коллаборация. Чтобы исправить опечатку в документации, разработчик или сотрудник поддержки должен написать письмо или завести баг, и станут ли они это делать - бабушка надвое сказала. Это лишний геморрой, а у них и так работы по горло. Процесс совместного ревью также затруднен. Чтобы сделать ревью документа, его нужно выгрузить в гуглдок или файл MS Word, отправить по почте нескольким людям, принять от них комментарии в документах и потом свести их воедино. Ревьюеры не видят комментарии друг друга, делают двойную работу и противоречат друг другу. Это неудобно и техническому писателю, и проверяющему.

• Отсутствие расширяемости. Проприетарные инструменты могут не иметь тех или иных важных функций (например, не поддерживать версионирование документации) или не удовлетворять каким-то другим параметрам (например, публикация может занимать продолжительное время, даже если вы исправили опечатку в одну букву). В таком случае, шансы что-то исправить минимальны. Если вы обратитесь к производителю, он в лучшем случае предложит кастомную разработку за внушительный ценник, в худшем - просто плечами пожмет. При попытке же перейти на другой инструмент, вы рискуете сполна познать прелести привязки к поставщику. Скорее всего, это будет сложно, дорого, и не застрахует от повторения старых и появления новых проблем.

• Стоимость. Лицензия на широко используемый продукт MadCap Flare обойдется вам в $149 на человека в месяц. Хотите воспользоваться облачным решением от MadCap? Готовьте $300. Незначительная сумма для большой организации. Большой удар по карману для маленькой фирмы или стартапа, еще не нашедшего стабильный источник финансирования.

Конечно, ни один из этих недостатков не является фатальным. Документация создавалась и еще долгие годы будет создаваться при помощи традиционных подходов и инструментов. Однако, если есть альтернатива, важно знать, в чем она заключается и чем она лучше. Что может нам предложить Docs as Code? Давайте узнаем вместе.

Дивный новый мир

Docs as Code это подход к разработке технической документации, который выглядит следующим образом:

• Документация пишется не в плейнтексте и не в формате WYSIWYG, а на языке разметки (например, Markdown, reStructuredText, Asciidoc).

• Документация хранится в репозитории Git.

• Документация собирается в нужный формат при помощи генератора статических сайтов (Sphinx, Hugo, Jekyll, MkDocs). Форматов может быть сразу много: HTML, PDF, DOCX и так далее.

• Документация пишется и обновляется коллаборативно.

К чему эти сложности?

Резонный вопрос. Какую головную боль лечит Docs as Code и в чем его преимущества перед классическим подходом? Преимущества есть, и их немало:

• Docs as Code использует знакомые разработчикам процессы и инструменты, что помогает вовлечь их в процесс создания документации. Это может быть большим подспорьем, если в вашей организации нет выделенного технического писателя и разработкой документации для продукта занимаются сами разработчики. Чудес, правда, ждать не стоит. Для того, чтобы и все заверте, скорее всего, придется терпеливо приучать разработчиков: Василий, смотри, вот ты десять минут заводил баг в Jira, заполнял все необходимые поля и расписывал по шаблону действительность/ожидания только для того, чтобы мы в лоб заменили на по лбу. А что бы было просто не кинуть нам пулл реквест? Быстрее и проще же.

• Использование репозиториев Git и связанных с ними процессов обеспечивает возможность поддерживать документацию для разных версий продукта, облегчает коллаборацию между сотрудниками, позволяет отслеживать авторов внесенных изменений, и дает возможность быстро откатить эти изменения, если нужно. До начала использования Docs as Code у меня в практике был случай, когда я, неправильно сориентировавшись в обстановке, дал сотруднику задачу, которую тот выполнял полдня. Через пару часов выяснилось, что внесенные изменения нужно откатить, чем я лично и занимался до самого вечера. Сейчас подобный конфуз решился бы за несколько минут.

• Использование генератора статических сайтов для публикации приносит с собой все связанные с этим преимущества - сайт документации грузится быстро и на нем нечего ломать.

• В отличие от проприетарных инструментов для разработки документации, функциональность инструментов Docs as Code безгранично расширяема и позволяет создать настолько мощную (или, наоборот, простую и дешевую) систему, насколько нужно именно вашей организации.

• Значительное (в несколько раз) сокращение временных затрат на рутинные операции. Публикация при помощи проприетарных инструментов запускается вручную и выдает через какое-то время готовый документ в формате .html или .pdf. Разместить его онлайн ваша забота. В результате имеем долгие, многоступенчатые процедуры публикации, требующие ручных действий на каждом из шагов. Публикация же с помощью Docs as Code может быть сведена к выполнению одной команды или даже полностью автоматизирована.

• Проприетарные инструменты для разработки документации требуют покупки одной или нескольких лицензий (зачастую весьма дорогих). Весь же цикл разработки документации по методологии Docs as Code можно выстроить при помощи свободного программного обеспечения. Это также порадует тех, кто отказывается от использования проприетарного ПО из идейных соображений.

Хотите страшную сказку на ночь? Я расскажу, как было у нас до того, как в Plesk появился Docs as Code. Мы использовали продукт под названием Author-It, и публикация документации с его помощью выглядела так:

1. Делаешь выгрузку HTML. Это могло занять от пяти минут до часа, в зависимости от размера гайда.

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

3. Пакуешь все это дело в архив и заливаешь по FTP на сервер.

4. Запускаешь сборку и ждешь еще полчасика. Молишься, чтобы не упало. Если упадёт, надо перезапускать.

Всё это счастье происходило при каждой публикации. Даже если ты поправил опечатку в одну букву. Это был неописуемо нудный процесс, жравший непристойное количество времени и часто приводивший к ошибкам. Забыл накатить стили перед публикацией? GOTO 20. Забыл накатить стили и уже успел удалить сгенерированные Author-it html-ки? GOTO 10. Теперь же наша документация собирается и публикуется по мерджу пулл реквеста автоматически. Автоматически, Карл! Пока не попробуешь сам, не поймешь, насколько же это круто! А сэкономленное время и внимание можно пустить на решение интересных задач.

Подводные камни

Перечитал предыдущий абзац - звучит, как будто я этим Docs as Code торгую. Что же, у нас на руках идеальное решение? Необязательно. Как и у любого другого подхода, у него есть своя специфика и недостатки:

• Отсутствие готовой, коробочной версии продукта. Все инструменты, нужные для Docs as Code, доступны, но запускать и настраивать систему вам придется самостоятельно. Будьте готовы к тому, что создание, обслуживание и совершенствование системы публикации документации потребует времени и технической экспертизы.

• Отсутствие off the shelf решения подразумевает и отсутствие технической поддержки. Если что-то пошло не так, некому завести срочный тикет. Придется разбираться самим при помощи комьюнити.

• Вашим техническим писателям нужно будет освоить работу с Git хотя бы на базовом уровне (git checkout/pull/commit/push + разрешение конфликтов при слиянии). Поначалу с этим возникнут трудности, и производительность может пострадать.

• Использовать языки разметки может быть не так удобно людям, привыкшим к WYSIWYG, особенно когда дело доходит до вставки иллюстраций и создания таблиц.

Антракт

Теперь вы знаете, что такое Docs as Code, и дальше рекомендуется читать, только если вам интересно не только что, но и как. Наше путешествие к Docs as Code началось в 2017 году. У нас было много энтузиазма и мало практического опыта, поэтому мы провели в пути дольше, чем планировали, и набили немало шишек. Об этом и пойдет речь дальше.

Но сперва я сделаю еще один реверанс. Прежде чем читать про как, давайте подумаем про зачем. Docs as Code в тренде, но не стоит бросаться внедрять хайповую технологию, не задав себе вопрос чтобы что? В нашем случае ответ выглядел следующим образом:

• Мы хотели ускорить и упростить процесс публикации - он занимал много времени и требовал ряда ручных действий в независимости от объема внесенных изменений.

• Нам нужна была поддержка версионирования, а Author-It не мог в него от слова совсем. Author-It позволял хранить и публиковать документацию только для одной версии продукта. Если нужно было внести изменения в документацию для более ранней версии Plesk, приходилось править HTML руками.

• Мы хотели сделать более удобным процесс ревью. Author-It умел выгружать топики документации в .doc, который потом высылался на ревью ПМу + разработчику + тестировщику. Сводить комментарии и изменения из нескольких вордовых файлов в один было тем еще удовольствием.

• Также хотелось оставить в прошлом некоторые заскоки Author-It. Например, он позволял молча и без подтверждения выкинуть из структуры гайда топик со всеми его подтопиками. И возможности откатить эту операцию при помощи Ctrl + Z не было. Сами топики при этом не удалялись, страдала только структура, и в теории ее можно было воссоздать руками. На практике было быстрее и проще зайти по RDP на виртуальную машинку, где крутилась серверная часть Author-It, развернуть более старый бэкап базы MSSQL, в которой Author-It хранил всю информацию, выгрузить неповрежденную структуру гайда в XML, снова подключить актуальную базу, удалить гайд, структура которого пострадала, а затем импортировать его из XML. Не шучу, время от времени приходилось заниматься подобным шаманством.

Мы рассматривали различные варианты нового механизма публикации, но все они по тем или иным параметрам не устраивали. Wiki не позволяла сделать версионирование и не имела наглядной структуры и оглавления. Confluence не имел внятной поддержки локализации кроме кошмарного варианта давайте сделаем отдельный спейс для каждой комбинации версия продукта + язык. Смотрели в сторону MadCap Flare, но в итоге отказались, решив, что нет никакой гарантии, что впоследствии не вылезут какие-то проблемы, которые снова заставят переезжать. В итоге выбор пал на Docs as Code как на вариант, обещавший в перспективе удовлетворить всем нашим требованиям.

Акт 2: Практика

Внедряем Docs as Code

Что же, вы решили внедрить в своей организации подход Docs as code. С чего начать?

Сформируйте список требований

Что должна будет уметь ваша новая система разработки документации. Например, нам нужна поддержка версионирования или мы хотим публиковаться в .pdf. Не пожалейте времени и составьте настолько подробный список, насколько сможете. Делать это лучше всего в формате мозгового штурма, в который нужно обязательно вовлечь всю команду технических писателей. Именно они лучше всего знают, какими возможностями обладает их текущий инструментарий, и каких возможностей им недостает. После того, как список сформирован, используйте его как чеклист на этапе проектирования. Прежде чем начинать работу по внедрению, пройдитесь по списку и убедитесь, что в том виде, в котором система спроектирована, она удовлетворяет всем требованиям.

Если вам кажется, что это долго и не очень-то и нужно, представьте, что вы ввели новый инструмент в эксплуатацию, потратив на это время, усилия, и деньги. А затем обнаружили, что он не обладает той или иной возможностью, необходимой для работы, потому что на этапе планирования о ней никто не вспомнил, и в требованиях она не была зафиксирована. Что, таблички? Нет, таблички нельзя создавать. Так ведь об этом не просил никто, вот мы поддержку табличек и не сделали. Не очень история, правда?

Планируйте

Прежде чем начинать работу по внедрению, тщательно спланируйте ваш проект, разберитесь в существующих технологиях и инструментах. Эта грабля нам довольно больно стукнула по лбу. Мы начинали внедрение Docs as code силами отдела технической документации. Когда стало ясно, что нам не хватает где-то ресурсов, а где-то экспертизы, пришлось обратиться за помощью к коллегам. Мы обсудили с ними цели и план работ и пришли к выводу, что некоторые из выбранных инструментов лучше заменить. В итоге часть уже проделанной работы оказалась на свалке.

Важный момент: если вы не собираетесь делать всё своими собственными мозолистыми руками, а планируете привлечь для внедрения другую команду или нанять разработчиков со стороны коммуницируйте, коммуницируйте и еще раз коммуницируйте. Пока не стошнит, если необходимо. Не дав себе труда убедиться в том, что исполнитель точно понимает ваши потребности, вы рискуете получить на выходе нечто, как будто сошедшее с известной смешной картинки:

Пользоваться таким чудом может быть неудобно, а в худшем случае и вовсе невозможно.

Документируйте

Не ленитесь документировать вашу систему Docs as Code. Особенно если вы делаете что-то более сложное, чем один репозиторий Git + генератор статических сайтов в стандартной комплектации. Да, на это всегда не хватает времени, но поверьте, усилия окупятся сторицей. Через пару лет вам не нужно будет морщить лоб, пытаясь разобраться, как же оно тут все устроено. Это что? Как оно работает? Кто писал этот код? Ах, человек уже год как уволился... Чем подробнее вы опишете детали реализации вашего решения, тем проще его потом будет поддерживать и модернизировать. Если вы решили заказать создание системы Docs as Code на стороне, обязательно включите ее документирование в список задач, необходимых для выполнения.

Решите, в каком формате вы хотите публиковать документацию

HTML? PDF? DOC? Все из вышеперечисленного? В зависимости от ответа на этот вопрос вам может лучше подойти тот или иной язык разметки. Например, из reStructuredText можно публиковаться во все три вышеприведенных формата, а классическая интерпретация Markdown конвертируется только в HTML.

Выберите язык разметки

Зная задачу, проще подобрать инструмент для ее выполнения. Существует целый ряд легковесных языков разметки, но два самых популярных из них - reStructuredText и Markdown:

Markdown

Из двух рассматриваемых языков разметки этот более простой, но и более ограниченный в плане форматов, в которые он может быть сконвертирован без дополнительных приседаний. Существует несколько имплементаций Markdown, ни одна из которых не является канонической. Например, GitHub Flavored Markdown обладает более широкими возможностями по сравнению со своим предком. Выбрав наиболее подходящую для ваших нужд имплементацию Markdown, убедитесь, что используемый вами парсер корректно превращает ее в HTML.

reStructuredText

Более мощный язык разметки, но и более капризный. В нем сложнее писать и проще допустить ошибку в синтаксисе (во всяком случае, пока не привыкнешь). Например, чтобы документ в reStructuredText не собрался корректно, достаточно пропустить или поставить лишний пробел или перенос строки. Большое преимущество reStructuredText в его расширяемости при помощи плагинов вы можете научить систему публикации распознавать и корректно отображать необходимые вам сущности (ссылки, таблички, вставки и так далее) в HTML.

Пример из недавнего нам нужно было добавить возможность вставлять выделенный рамкой текст. Мы используем такое выделение для краткого описания содержания статей документации. Так пользователь может за несколько секунд понять, в нужную ли статью он зашел. Изначально подобного функционала у нас не было. Но за несколько часов у нас появилась возможность добавлять подобные вставки при помощи такого форматирования:

.. admonition:: summary

Hello world!

Собираем HTML и видим вот такое:

Какой язык разметки используется в Plesk? Мы подумали и решили:

Это не шутка мы действительно используем на нашем портале документации и reStructuredText и Markdown. Зачем? Все просто: мы используем разные языки разметки для решения разных задач с разными требованиями:

• reStructuredText используется для написания документации. Для этой задачи нам в первую очередь важны богатые возможности форматирования, а также расширяемость.

• Markdown используется для написания release notes. Мы пишем их много и часто, а требования к форматированию минимальны - болд/италик/моноспейс/кодблок/ссылки. Для этой задачи нам важнее всего простота и скорость использования.

Чтобы понять, какой язык разметки лучше подходит для ваших нужд, можно начать с этой статьи в Wikipedia. В ней рассматриваются сравнительные характеристики различных легковесных языков разметки, а также примеры синтаксиса.

Выберите инструмент для публикации

Вы определились с языком разметки. Пора выбрать инструмент, при помощи которого вы будете документацию публиковать. Вариантов несколько, но в этой статье для начинающих я хотел бы сфокусировать внимание на четырех: Hugo, Jekyll, Sphinx и MkDocs. По сути, все они являются генераторами статических сайтов. Hugo и Jekyll больше ориентированы на блоги, а Sphinx и MkDocs специально заточены для создания документации и обладают большим количеством полезных в этом деле фич из коробки. Все четыре инструмента популярны, широко используются, поддерживаются и имеют активное комьюнити.

Если выбор вас пугает, не переживайте. На самом деле, часть опций вы отсекли еще на предыдущих шагах. Генераторы статических сайтов поддерживают, как правило, один-два языка разметки. Если на предыдущем шаге вы выбрали reStructuredText (расширяемость наш выбор, а синтаксис выучим), то ваш главный кандидат Sphinx. И ваш выбор инструментов будет куда шире, если вы проголосовали за Markdown (мы не хотим возиться с reStructuredText и разбираться, почему после трех коммитов, призванных исправить ошибки форматирования, HTML собирается вкривь и вкось).

Конечно же, поддерживаемые языки разметки - далеко не единственный фактор, на который нужно обратить внимание. Каждый инструмент обладает различными возможностями, и какой из них лучше подойдет под именно ваши нужды - решать вам.

В Plesk для сборки документации мы используем Sphinx, а для сайта портала документации целиком - Jekyll. Это позволяет расцепить механизмы обновления непосредственно руководств и других страниц, размещенных на портале документации, например, чейнджлога или FAQ. Благодаря этому публикация release notes для новых версий продукта и его расширений занимает меньше минуты.

Сделайте красиво

Ну или хотя бы так, чтобы сайт документации не выбивался из общего стиля вашей организации. Каждый из рассматриваемых в статье инструментов поддерживает использование тем, меняющих внешний вид создаваемых ими страниц. Есть широкий ассортимент доступных и бесплатных тем. Если у вас нет возможности сделать оформление под себя самостоятельно или заказать подобную услугу, имеет смысл ознакомиться с ассортиментом доступных тем заранее, чтобы потом не вздыхать эх, нам бы то же самое, но с перламутровыми пуговицами.

Что насчет существующего контента?

Возможно, у вас уже есть сайт с документацией. Что же, при выборе Docs as code вам придется выбросить его или заново набивать руками? Не обязательно. Существуют решения для конвертации текстов из одного формата в другой, но с ними тоже придется разбираться. Как тут поступить зависит от объема существующей документации. Если у вас есть десяток-другой документов, возможно, будет проще, скрепя сердце, набрать их заново в выбранном языке разметки. В Plesk массив документации насчитывал приблизительно четыре с половиной тысячи документов, поэтому для нас подобный вариант не был реалистичным. В итоге мы без потерь сконвертировали всю существующая документацию из .html в .rst при помощи инструмента Pandoc.

Определитесь с версионированием

Если вы разрабатываете SaaS продукт или агрессивно пушите пользователей обновляться, поддержка версионирования вам вряд ли потребуется. Но что делать, если вам нужно поддерживать и предоставлять пользователям документацию для двух или более версий продукта?

Дешевое решение паковать собранную документацию для старых версий продукта в архивы и делать их доступными для скачивания. Мы так поступаем с документацией для ушедших в EOL много лет назад версий Plesk, которыми уже почти никто не пользуется. Но это неудобно для пользователя. Клиент на старой версии продукта вряд ли сможет найти вашу документацию при помощи Google или другой поисковой системы (для справки: на docs.plesk.com органический поисковый трафик составляет более половины посетителей).

Нам было важно дать клиентам доступ к документации последней и предпоследней версий Plesk (Onyx и Obsidian) и сделать так, чтобы отдельная страница со своим контентом и URL была у обеих версий. Мы реализовали это следующим образом: в каждом репозитории Git, содержащем исходники того или иного руководства, есть несколько веток. Каждая ветка содержит исходные файлы для той или иной версии продукта, что позволяет вносить изменения в документацию, например, для Plesk Obsidian, при этом никак не затрагивая документацию для Plesk Onyx. Есть и недостаток: когда нужно обновить документацию для всех версий продукта сразу, приходится делать коммиты в каждую ветку по очереди, что тоже занимает время.

Ду ю спик инглиш?

Возможно, вам понадобится переводить вашу документацию на иностранные языки для ваших клиентов. Если так, то стоит заранее подумать о том, как вы будете работать с переводами.

Самый простой в реализации вариант создать отдельную ветку или репозиторий, сделать в нем копию исходников на языке, на котором вы пишете, а затем в этой же ветке или репозитории переводить. И так для каждого языка, отличного от исходного. На практике такой подход вряд ли практичен он требует от переводчиков навыков работы с Git и знания синтаксиса .rst. К тому же, если вы планируете работать со сторонними переводчиками, нужно будет внимательно настроить им права доступа, чтобы они не могли видеть, например, исходный код продукта. Вдобавок, это создаст постоянную головную боль процессного плана: обновили документацию нужно дать знать переводчикам, что они должны отразить изменения и в своих исходниках.

Мы пошли более затратным в реализации, но куда более дешевым в использовании путем. Мы разбиваем исходные документы на английском языке на единицы перевода (заголовки, абзацы все, что с обеих сторон ограничено переносом строки). Переводы руководств на все языки хранятся в том же репозитории/ветке, что и само руководство в виде .po файлов. Содержимое их выглядит так:

#: ../../../../projects/administrator-guide/source/53231.rst:15

msgid "You can choose to:"

msgstr "Folgende Optionen stehen zur Verfgung:"

Здесь мы видим перевод единицы перевода из репозитория administrator-guide, документ 53231.rst, строка 15. В наличии как исходная строка, так и ее перевод на немецкий (всего в данном .po файле шесть таких единиц, некоторые поменьше, некоторые побольше). В итоге все содержимое документа на английском покрывается переводом. При сборке документации на немецком механизм берет исходный файл .rst и автоматически заменяет единицы перевода в нем на переведенные. Данный подход позволил нам интегрироваться с сервисом Crowdin, в котором работают наши переводчики. Они пользуются привычным им интерфейсом мы получаем переводы.

Автоматизируй это

Одно из основных преимуществ подхода Docs as code - возможность использовать инструменты непрерывного развертывания, чтобы передать связанные с публикацией рутинные операции на попечение роботов. Не пренебрегайте им. Чем чаще вы вносите изменения или публикуете новые документы, тем больше времени автоматика вам сэкономит. С тех пор, как мы внедрили автоматическую публикацию по слиянию, автоматика экономит нам минимум один-два (а зачастую и больше) человеко-часа каждую неделю, а также исключает подобные драматические сцены:

-Василий, почему релиз ноты еще не на продакшене? Два часа как вышло обновление, клиенты жалуются (у нас были подобные случаи и клиенты действительно жалуются)!

-А, черт, я закоммитил, а запустить сборку забыл :(

В Plesk мы реализовали непрерывное развертывание документации при помощи Jenkins - он уже используется для разработки и публикации самого продукта, и мы решили не изобретать велосипед. Для публикации документации и релиз нот используются разные пайплайны. Схематично выглядит это так:

1. При слиянии ветки с изменениями в основную, сервер Jenkins запускает сборку гайда, в который были внесены изменения (.rst => .html), на всех языках, на которые он переведен, а также обновляет файлы .po, которые пойдут потом на перевод. Если мы публикуем релиз ноты, этот шаг пропускается.

2. Пересобирается сам портал документации, включая релиз ноты, FAQ и все прочие находящиеся на нем страницы.

3. Собранная документация разворачивается на сервере.

4. Сети доставки содержимого подается команда сбросить кэш.

Здесь есть еще одна тонкость. Кроме Plesk, мы публикуем множество расширений к нему, и каждый новый выпуск каждого из расширений тоже сопровождается своими релиз нотами. Они становятся доступными к сборке документации как только попадают в основную ветвь, поскольку для них время публикации не особо критично. Но для обновлений самого Plesk релиз ноты должны появиться в публичном доступе одновременно с выходом обновления, иначе сразу начинают сыпаться запросы от клиентов ("Мой Plesk автоматически обновился, где я могу прочесть об изменениях?", "Я вижу на портале документации релиз ноты для обновления Plesk, как мне его поставить?"). Во избежание подобных ситуаций, релиз ноты для основного продукта становятся доступными к сборке документации и публикуются строго в рамках публикации обновления Plesk.

Заключение

Нужен ли вам Docs as code? Зависит от. Если у вас небольшая компания, несложный продукт, устоявшиеся процессы и дюжина страниц документации, которые вы обновляете раз в квартал пожалуй, выхлоп не окупит затрат на внедрение. Если же вас заинтересовали описанные в моей статье возможности, или вы просто любите быть на острие прогресса почему нет? Просто заранее вдумчиво спланируйте вашу будущую систему Docs as code исходя из ваших уникальных потребностей, и я уверен вы не пожалеете :)

Спасибо за внимание!

P.S. Хочу также сказать "спасибо" Николаю Волынкину, Дмитрию Ширяеву и Катерине Говердовской за участие в работе по созданию и наполнению нашего портала документации, а также за помощь в написании статьи.

Чем проще и понятнее описаны требования тем меньше багов будет в функционале. Потому что не будет разных прочтений, додумок и прочего. А еще в простыне текста легко потеряться и что-то просто забыть реализовать.

Как же сделать ТЗ понятнее? Можно улучшить текст вместо скупого текста составить вариант использования. А можно использовать визуализацию. То есть добавить в требования картинки, диаграммы, таблицы...

Причем сделать это может не только аналитик, но и любой член команды. Тестировщикам особенно полезно визуализировать ТЗ, потому что это помогает сразу увидеть проблемные места и уточнить их ещё до реализации. Раннее тестирование и всё такое =)

А ещё техники, помогающие лучше понять требования, относятся к техникам тест-дизайна. Значит, о них стоит знать! В одну статью всё запихивать не стала и сделала отдельные:

1. Вариант использования

2. Decision Table (таблицы решений)

3. State & Transition Diagram (схема состояний и переходов)

Но значит ли это, что таблица или S&T единственный способ визуализации? Разумеется, нет! Можно рисовать вообще всё, что вам вздумается. Главное чтобы картинка помогала лучше понять требование или тест (да, при описании тестов визуализация тоже помогает!).

И сегодня я покажу разные примеры визуализации из своей практики, или работ моих студентов. Может, что-то из этого приглянётся и вам! =)

1. Как рисовать картинку

2. Примеры

3. Плюсы подхода

4. Минусы подхода

5. Инструменты для рисования

6. Итого

Как рисовать картинку

Берем требование и представляем в графическом виде. Всё!

Главное отличие от S&T в том, что нам необязательно рисовать именно объект. Мы рисуем всё, что захотим. Всё, что поможет сделать ТЗ более читабельным, да хоть интерфейс в виде карты! Или блок-схема, или что-то ещё.

Примеры

.

Карта сценариев

Функционал взаимодействия с конкретной книгой (взято из работ моих студентов):

Это карта сценариев, а не S&T, но он этого она не менее полезная!

.

Загрузка инкремента

Блок-схема про то, как это работает под капотом. На одном из проектов мы сделали довольно хитрую схему импорта данных из буферной таблицы. Для пользователей написан вариант использования, и там всё просто:

• Исходная система выгрузила данные в буферные таблицы.

• В таблице increment добавила номер выгруженного инкремента это будет флаг для нашей системы начинать забор данных.

А на нашей стороне надо проверить таблицу инкрементов, попробовать выбрать новый инкремент, создать новые карточки, обновить существующие... Если смотреть через админку, это три разные задачи:

1. Подготовка данных

2. Загрузка

3. Очистка буфера

Каждая задача выполняет внутри кода несколько действий. А мне надо подготовить набор автотестов на каждый этап. Значит, надо разобраться, что там происходит. Я сначала долго тупила над пользовательской докой, пытаясь понять, как оно устроено внутри, а потом пошла к разработчику и попросила объяснить для блондинок.

Это было продуктивное общение! Пока он объяснял, я рисовала на бумажке схему и задавала по ней вопросы. После нескольких вопросов раработчик признал, что я молодец, он про вот это и то не думал. Не зря рисовала! Без рисунка я бы просто не удержала всё в голове, и не обнаружила проблемные зоны.

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

1. null => 1. Выбираем все записи из таблицы INCREMENTS, где import_status is null и устанавливаем им значение import_status = 1.

2. Удаляем неактуальные записи из буферных таблиц (физ лица и телефонов).

3. Грузим физиков по условию in (id_increment, для которого import_status in 1).

4. Грузим телефоны по условию in (import_status in 1).

5. Создаем связи телефон - физик или телефон - юрик (тип контрагента смотрим по таблице staging).

6. Удаляем физиков из буфера, если не было ошибок на этапе загрузки.

7. Удаляем те телефоны, у которых есть связи (проверяем наличие record_id физика/юрика в staging).

8. 1 => 2. Выбираем все записи из таблицы INCREMENTS, где import_status = 1 и устанавливаем им значение import_status = 2.

Согласитесь, при наличии такой картинки тесты на каждый раздел писать намного проще! Я четко вижу, что задача подготовки выполняет три действия. Значит, тестируем каждое!

null => 1. Выбираем все записи из таблицы INCREMENTS, где import_status is null и устанавливаем им значение import_status = 1.

Добавляем запись с пустым import_status проверяем, что статус изменился на 1.

А если исходно был статус 1?

А если исходно другой статус?

Так, дальше идет вызов oracle-процедуры. На схеме записано, как она называется ищем по названию в коде, изучаем, что она делает. И готовим тестовые данные, как позитивные, так и негативные.

Что у нас дальше? ...

И так по каждому пункту. Потом, когда к проекту подключались другие люди и тоже не могли понять, как тестировать задачу, я давала ссылку на эту страничку в конфлюенсе. И все сразу вставало на свои места!

Так что я продолжила традицию. Если есть какой-то сложный алгоритм думала, как его можно зарисовать (блок-схема, диаграмма, кружочки и стрелочки, что угодно!), а потом заносила в раздел с техническими подробностями.

.

Тесты в PowerPoint!

Метод рисунка работает не только с ТЗ, но и с тестами!

Тестировала оракловые вьюшки (view). Фактически это просто табличка с нужными мне колонками. Как любой отчет в интерфейсе. Cтроится отчет по определенному диапазону времени. Если сущность менялась в этом диапазоне она попадет во view. Если нет то увы.

На входе у меня есть текущее состояние базы когда объект был создан, а когда закрыт. И параметры диапазона:

• from_date начальная дата

• to_date конечная дата

Я набросала все интересные мне тесты в блокноте это быстрее всего. Допустим, объект создали 5 числа, а удалили 10. Какие интервалы между ними мне надо посмотреть?

Рисунки помогают мне быстро охватить картину покрытия тестами. Так, вот только создание попадает в диапазон есть. А оба события сразу есть. А между ними? Есть. А... И так далее. Накидаешь идей за пару минут мозгового штурма, и можно с ними работать. Переносить в код и описывать на вики.

По мере разработки тестов я вычеркиваю их зеленым маркером если меня отвлекут, то, вернувшись к работе, я всегда легко пойму, какие тесты уже сделала, а какие еще осталось. Не потеряю мысль. А цвет прозрачный, вычеркивание не мешает читать.

Но с переносом в вики проблема если описывать текстом, получается унылая фигня. В блокнот взгляд кидаешь все понятно. Это покрыл, это покрыл, это покрыл. В вики смотришь... И нужно мысленно в уме рисовать, чтобы увидеть общую картину. Неудобненько. В таких случаях я добавляю к описанию рисунки.

Обычно я рисую в yEd. Но черточки и текст отдельно там сделать проблематично. Тут не подходит. Хм... Paint? Открыла его, нарисовала кривую "прямую" :) Тоже неудобно, хочется, чтобы симпатичненько смотрелось, а мышкой я прямые линии буду полчаса рисовать. Visio покупать надо... О, PowerPoint!

Открыла, попробовала. Поставила исходные засечки "создан 5, закрыт 10". Добавила прямоугольник на задний план идеально! Просто перетаскиваешь прямоугольник, то сужая, то расширяя его, и делаешь скриншоты. А как наглядно получается:

Добавим картинки в описание тестов на конфлюенсе (вики):

Красота!

Вы только представьте себе всю унылость описания, не будь картинок. Вот задали тебе вопрос, как поведет себя система, если диапазон такой-то. Навскидку не помнишь? Посмотри в тестах! Открываешь описание и пытаешься вкурить, где подходящий тебе случай. А так открыл, пробежался глазами по картинкам и быстренько все нашел.

Есть картинки и посложнее. Когда событий будет поболее, чем просто "создали один объект и его же закрыли". Тут мне было удобнее рисовать время по вертикальной оси:

Вот тут то меня PowerPoint и выручил! Если делать зарисовки от руки, то на каждый тест надо повторять основу, а потом обводить кружочком нужный диапазон. Получится долго. А без визуализации "что я уже сделала" мне тяжело. А в программе вжух-вжух поперемещал желтый прямоугольничек, заскринил каждую вариацию и готово! Даже круче блокнотика и ручки :)

Плюсы подхода

Визуализация!

1. Позволяет увидеть, что мы упустили

2. Помогает там, где много входных условий

Двойной профит визуализации: пока вы рисуете, то видите все слабые зоны ТЗ. А ещё делаете его более наглядным. Теперь каждый, кто будет читать ТЗ после вас, сразу всё поймет!

Минусы подхода

Картинку должен кто-то поддерживать, и это кто-то явно вы =)

Но всегда можно нарисовать ее одноразово!

Инструменты для рисования

1. Бумага и ручка!!

2. Маркер и доска

3. Xmind (freemind, etc)

4. Microsoft Visio

5. PowerPoint

6. YeD

7. ...

Если задача простая используйте бумагу и ручку. Будет быстрее.

Если задача сложнее возьмите инструмент. Любой, хоть paint. Ведь фишка не в инструменте он лишь помогает вам сформировать мысль. Чем проще инструмент, тем лучше. Чем проще рисунок, тем круче. Вы ведь не Мону Лизу рисуете, а только набросок, который помогает понять тест.

Итого

Рисунок мощнейший инструмент визуализации. Если вам сложно что-то понять, зарисуйте это! Это может быть сложный участок ТЗ или чек-лист тестов. Пробуйте, экспериментируйте это время обязательно окупится. Причем сразу же, ведь, пока рисуешь, приходит вдохновение "проверить еще вот тут"!

PS больше полезных статей ищитев моем блоге по метке полезное. А полезные видео намоем youtube-канале

Богатый язык инженера - это ещё один способ утвердить свой профессиональный уровень в глазах окружающих.

- Ооо, ты инженер конструктор?

- Да!

- Скажи что-нибудь как инженер конструктор!

-Крыльчатка насоса.

- Бог с ним, отправляй, по замечаниям исправим...

Профессия Инженер - компактное название с громоздким синтаксисом и семантикой. Благодаря труду инженеров страны развиваются, а население выходит на новый уровень жизни. Каждый из нас хоть раз восторгался видом чего-то нового например, ракеты или новой машины. Мы путешествуем в разные страны, в том числе, с целью посмотреть на технические выставки и развитие стран, то есть, на работу инженеров. Однако за каждым открытием и творением стоит ни с чем не сравнимый труд. И в каждом открытии и творении стоит инженерная мысль, возможно, уникальный проект инженера.

Сейчас, в 21 веке, особенно после пандемии и переживаемого экономического мирового кризиса, очевидно то, что надо либо иметь стабильную зарплату в крупной фирме, желательно государственной (с фиксированным окладом), либо уходить в свободное плавание и закладывать почву для другой жизни с желаемым уровнем дохода. Для этого надо составить и проанализировать сводку подводных камней, поджидающих тебя на пути к свободе и воплощению своих амбиций.

В данной статье рассмотрим проблемы фриланса на примере профессии Инженер проектировщик в машиностроении. На протяжении всей истории человечества изобретателей недооценивали. Ничего не изменилось и сейчас: на полках патентных бюро пылятся миллионы чертежей, которые еженедельно пополняются новыми и новыми диковинками. Изобретатель обычно может рассчитывать на очень скромное вознаграждение за свой труд: даже если его идею берут в работу, авторские отчисления, как правило, весьма невелики.

Причина в том, что настоящее изобретение состоит из двух частей технической части и бизнес-части, причём смастерить бизнес-часть обычно значительно сложнее. Изобретатели, которые выполняют работу целиком, выстраивая собственными руками конвейер по производству собственных изобретений, получают от общества щедрое вознаграждение за свои труды. Так, к примеру, если бы Генри Форд жил в наше время, он имел бы состояние в 200 млрд долларов и был бы богатейшим человеком планеты, создание своего конвейера с исследовательским опытным бюро и производством это отдельная тема.

Выделю проблемы, поджидающие проектировщика после закрытия дверей работы на дядю/тетю, и сразу пути их решения как на деле, так и в своей прекрасной головушке:

• Создание проекта с подробным описанием задачи

Итак,подстава 1

Все зависит от полноты и качества информации на начальной стадии ТЗ. Во избежание переделок старайся навязать заказчику начало сроков проектирования только после утверждения эскизной проработки всех узлов устройства. Если заказчик даже немного адекватен, то идет навстречу, потому что тоже не хочет, чтобы вертикальный виброконтейнер с эксцентриковым электрическим приводом оказался с гидравлическим или вообще без привода=)) Так что на 1-м этапе чаще всего идет подбор вариантов компоновки и подбора комплектующих. И тут, как правило, становится ясно, что же хочет заказчик проекта. Ведь он "всегда прав". Главного конструктора, который должен постоянно держать руку на пульсе проекта и сам увязывать все дополнительные пожелания у тебя нет, поэтому требуй качественное ТЗ.

• Несерьезность, студенчество, подработка;

Подстава 2

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

Может показаться, что занимаешься ерундой, что это не серьезно брать заказики, сидя и диване и потягивая чаек, где так спокойно и уютно, никто не доканывает, не маячит перед глазами и не создает чувство важности и ответственности. В таком случае, я предлагаю вспомнить, ради чего ты все это затеял и ушел в сенсорную комнату под сладким названием Фриланс, обозначить еще раз плюсы лично для себя, научиться быть ответственным перед собой, и побыть морем поволноваться и успокоиться.

• Наличие привлекательного портфолио с результатами сложных расчётов, проектирования, фото.

Подстава 3

Если у тебя пока нет портфолио, то это может быть похоже на неуважение как к себе, так и к потенциальным клиентам, может показаться, что ты даже (О, Боже) перекупщик. Конечно, в наше время реклама занимает чуть ли не первую ступень в становлении успешной личности, поэтому продумай заранее, как и какое портфолио тебе подготовить. Можешь даже вспомнить раздел из производственной эстетики и подобрать разные цвета к фону твоих работ.

• Оплата больничных;

Подстава 4

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

• Когда заказчик - начальник, а ты хотел от этого уйти;

Подстава 5

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

• Нет постоянной загруженности и стабильных денег;

Подстава 6

Быстрее, выше, сильнее. В империю нарциссизма надо до смерти хотеть все успеть, охватить, стать лучшей версией себя, выйти из зоны комфорта (хотя это термин был придуман для бизнеса изначально). Тут может получиться, что пропадет мотивация, если ты заметишь себя за 8-м часом черчения проекта стоимостью 700 рублей, например. Выдохни! Этот заказ может быть таким, но это вовсе не значит, что все заказы одинаковые. И с этой прекрасной мыслью повысь износостойкость своей нервной системы - забей на все, выпей чаю, дочерти, и верь в следующий заказ. Желательно верить сильно, а то захочется вернуться на работу, позабыв, как все начиналось.

• Общение с коллегами;

Подстава 7

Сначала ты радуешься, что избавился от токсичной коллеги, скучаешь по остальным прекрасным товарищам, а затем ты просто скучаешь по всем, даже по токсичности коллеги, по эмоциям. Хоть каким-то. Да, энергообмен с людьми важен, поэтому общайся на форумах, ходи на тематические выставки, вебинары, общайся с друзьями, выходи из комнаты.

• Придётся постоянно развиваться в направлениях, о которых ты возможно раньше и не задумывался (либо не хотел задумываться): продажи, маркетинг, бухгалтерия, стратегия и тактика ведения переговоров, сильное имя и многое другое.

Подстава 8

Не, ну это подстава, конечно, ну, а как ты хотел? Век живи век учись. Тут придется похлопотать над прокачиванием себя в этих областях, хотя бы до уровня новичка-любителя, чтобы не платить таким же фрилансерам за помощь. Ролики на youtube, вебинары, семинары все в открытом доступе, понятно, читабельно, разжевано. Дерзай, это не трудно, въедешь, что по чем, и будет легко.

• Инженерный фриланс в СНГ развит очень слабо, поскольку инженерная деятельность, как правило, очень сильно привязана к конкретному производству.

Подстава 9

Есть такое, но это не проблема века. Все в твоих руках. В помощь Peopleperhour, Профессионалы ru, weblancer net, Linkedin, Яндекс Услуги , а также твои знакомства. Вспомни метод неполной взаимозаменяемости, где требуемая точность замыкающего звена размерной цепи достигается некоторым заранее установленным риском путем включения в нее составляющих звеньев без выбора, подбора или изменения их значений. Размещай резюме везде ыыыы!! Где-то точно выстрелит.

• В регионах нужно ИМЯ

Подстава 10 или опытные дядьки

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

• Тайм менеджмент

А это вот не подстава, акрутая тема.

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

Будь в меру жестким, в меру податливым, но особо не деформируйся под воздействием внешних сил! Будь собой! Каждый, кто по-прежнему считает, что хорошо там, где нас нет, все вышеупомянутое не пугает, а воодушевляет, манит чертежами и моделированием изобретений под солнцем и пальмами на Бали, а трудности с первым заработком в первые несколько месяцев мотивируют, то жду всех с вопросами, предложениями и комментариями!

По виду деятельности элементы делятся на: Атомарный и составной.

По типу модели: Процессный и хореография.

Рассмотрим сочетания:

1. Задачи(task) - это атомарная деятельность, которая находится внутри процесса.

2. Подпроцесс (sub-process) это составная деятельность, которая находится внутри процесса.

3. Задача хореографии (choreography task) это атомарная деятельность в хореографии.

4. Подхореография (sub-choreography) это составная деятельность внутри хореографии.

   Данное видео является частью "Базового видео-курса по BPMN"

BPMN предназначен, прежде всего, для описания моделей процессов на предприятии. Для описания моделей обмена данными на предприятии А также для генерации кода в формате XLM для BPMS систем.

BPMN помогает в решении следующих задач:

• Реорганизация работы коллектива

• Автоматизация деятельности сотрудников

• Автоматизация деятельности сотрудников в BPMS

Реорганизация работы коллектива заключается в том, что на основании построенной модели бизнеса в работу сотрудников вносятся определенные изменения.

Это позволяет:

• оптимизировать рабочий процесс,

• улучшить взаимодействие между подразделениями,

• повысить результативность.

Автоматизация деятельности сотрудников помогает в создании технического задания для программистов. Если мы говорим об автоматизации в BPMS, подразумевается, что BPMN позволяет создавать исполняемые графические нотации.

Для реорганизации создаются две модели:

AS IS - Как было. Эта модель описывает текущую ситуацию в работе компании.

TO BE Как должно быть.

После анализа существующей ситуации выявляются проблемные места и вносятся необходимые изменения. В результате мы можем наглядно увидеть, как было и как должно быть. Показать разницу лицам, принимающим решения, обосновать предложенные решения.

При работе в BPMN вы можете пользоваться двумя типами графических моделей исполняемыми и неисполняемыми. Исполняемые модели позволяют на основе графики автоматически генерировать исполняемый программный код. У них есть свои особенности синтаксиса, несколько сложнее и строже в сравнении с неисполняемыми моделями. Но и плюсы очевидны. Вместо длительного ручного труда программиста готовый код, который можно использовать в BPMS системах.

Данное видео является частью "Базового видео-курса по BPMN"

Чаще всего руководитель бизнеса и программист говорят на разных языках. В итоге программист работает либо вообще без тех. задания, т.е. составляет его себе самостоятельно на основе того, о чем он сам догадался в беседе с клиентом, либо получает ТЗ, которое на самом деле вынуждает его делать не совсем то, что реально нужно клиенту.

Более того, любой IT-специалист без исключения ограничен в выборе решения своей специальностью. Так, 1С-специалист будет привычно дорабатывать под поставленную задачу какую-либо 1С-конфигурацию в то время, когда для решения проблемы может быть достаточно Excel-таблицы или отдельной программы для рассылки почты.

Бизнес-консультант это тот самый человек, который сумеет провести грамотную диагностику проблем, возникших в вашем бизнесе. Он привык смотреть не только на явные симптомы, но анализирует весь бизнес-процесс. После чего бизнес-консультант назначит вам правильное лечение. У него есть практический опыт, есть знание и понимание ошибок ваших коллег, есть разные варианты решений, проверенные на практике. В отличии от программиста, он должен выбирать каждый раз оптимальное решение, не зацикливаясь на каких-то привычных инструментах.

Данное видео является частью "Базового видео-курса по BPMN"

Для того, чтобы понять, что такое BPMN, следует для начала разобраться с тем, что такое WSBPEL.

Расшифровывается эта аббревиатура как:

Web Service Business Process Execution Language, а переводится как - Исполняемый язык бизнес процессов.

Давайте разбираться, зачем этот язык нужен. Независимо от сложности и особенностей информационных систем , на определенном этапе возникает вопрос их интеграции между собой. И WSBPEL используется как раз для того, чтобы интегрировать одну IT-систему с другой. Эти системы могут быть написаны на самых разных языках. Но при помощи WSBPEL мы можем организовать между ними обмен данными.

Например, интегрировать учетную систему и сайт.

Но у WSBPEL есть как плюсы, так и минусы. Разберемся с плюсами:

• Понятно программисту. То есть, так как WSBPEL это язык программирования, программисты его легко понимают.

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

В результате, интеграция систем при помощи WSBPEL дело сложное, но понятное программисту. Поэтому пользоваться WSBPEL программисту проще, чем писать какие-то конструкции с нуля. Но у этого решения есть и ограничения. Оно не понятно консультантам и в нем трудно менять логику. Понятно, что консультант не программист, и ему сложно будет читать код. Кроме того, чтобы изменить логику, также придется изучать особенности кода. Это доступно программистам, но для консультанта это недоступно. Особенно, если писал код другой человек.

Бизнес-аналитикам удобнее блок-схема. Это может быть любой набор графических элементов пиктограммы, блоки, стрелки. Это все просто, наглядно, понятно интуитивно.

Итак, очевидна необходимость совместить удобные инструменты для бизнес-аналитика и работу с кодом для программиста. Так появился BPMN. С одной стороны, этот инструмент использует графический подход к описанию бизнес-процесса, с другой стороны при определенных условиях он способен из графической нотации сгенерировать программный код.

Данное видео является частью "Базового видео-курса по BPMN"

Истина любит критику, отнеё онатолько выигрывает; ложь боится критики, ибопроигрывает отнеё.

Дени Дидро

Да да, товарищи, именно за этим я пишу эти строки. Я решил выпустить видео-курс на Habr. Именно для нее, для критики.

Тем, кто ещё не знает что такое рекомендую ознакомиться с моей статьёй: "Как описать бизнес-процесс в формате нотации BPMN. Пошаговая инструкция + видео"

Итак:

1. Курс бесплатный

2. Все видео указанные в списке будут выкладываться в общий доступ на Youtube

3. Список неполный, я буду добавлять видео по мере поступающей информации.

4. Каждое видео будет в виде поста на хабре с описанием

5. Каждое добавление будет отражено в таблице.

6. Делаю я видео в свободное время в среднем по одному в день.

Каждый видео-урок с подробным описанием будет опубликован в моём блоге для возможности обсуждения и получения обратной связи.

Ответы на вопросы:

1. Зачем я это делаю бесплатно?

   Потому что могу.

2. Зачем дублировать видео-курс на Youtube-канале и на Хабре?

   Мне интересно ваше мнение - мнение специализированной аудитории Habr.

3. Какое программное обеспечение было использовано для создания данного видео?

   Keynote.

4. Что делать, если я не являюсь пользователем Youtube и Хабра?

   Зарегистрироваться на хабре и/или на Youtube.

Токен это теоретический концепт, который используется для понимания поведения рассматриваемого процесса.

Поведение элементов процесса может быть понято через то, как они взаимодействуют с токеном, который перемещается по структуре процесса. Между тем в системах исполнения и моделирования, использующих BPMN стандарт, не обязательно в каком-либо виде указание токена.

В видео применение рассматривается на примере трех сценариев.

Данное видео является частью "Базового видео-курса по BPMN"

Пул (pool) это графическое представление Участника в коллаборации.

Пул изображается прямоугольником. Пул может не изображаться специально, но как элемент диаграммы он всегда присутствует.

Данное видео является частью "Базового видео-курса по BPMN"

В прошлой статье я предложил рассмотреть Xwiki, как бесплатную замену Confluence и заодно пообещал поделиться несколькими советами по настройке.
Вот уже больше полугода я использую Xwiki в качестве базы знаний для небольшой команды разработчиков.
В процессе работы у меня возникали определенные трудности, документация не помогала, а ответов на англоязычном форуме приходилось ждать с большим вожделением, чем первого глотка пива в выходной.

Мне бы хотелось облегчить жизнь энтузиастам из волшебного мира документирования, поэтому я решил поделится своими наработками.
На текущий момент я планирую подготовить мини цикл из четырех - пяти статей про Xwiki.

В первой статье мы погорим о простых вещах, которые не отнимут у нас много времени, а именно:

• как сделать оглавление страницы в боковой панели;

• как сделать свою панель навигации;

• как добавить свои советы в панель подсказок;

  • за одно узнаем, как сделать аннотацию на странице;

  • также узнаем, как использовать проверку орфографии в WYSIWIG редакторе;

Прежде чем мы начнем, хочу признаться, что я далеко не "гуру" в программировании и настройке Xwiki, так, что это просто "не очень элегантные" советы, которые тем не менее работают.

Весь материал статьи я проверял в версиях Xwiki 12.10.5 и 13.2 с установленной Demo Flavor. Также в статье подразумевается, что вы обладаете правами администратора.

Оглавление страницы в боковой панели

В админ-панели переходим в раздел Настройки интерфейса -> Мастер панелей и внизу страницы находим ссылку "Перейти к панелям". Ну или просто введите в адресную строку
{ваш домен с Xwiki}/bin/view/Panels/
В разделе "Создать новую панель"
Введите название панели (например, SideTOC} и нажмите кнопку "Создать"
Тип панели оставьте - "View"
Описание - на ваше усмотрение.
В поле Содержимое введите код:

{{velocity}}{{context document="$services.model.serialize($doc.documentReference)" transformationContext="document"}}#set ($hasHeaders = [])#set ($mydoc = $doc.getDocument())#foreach ($block in $mydoc.getXDOM().getBlocks('class:HeaderBlock', 'DESCENDANT')) #set ($discard = $hasHeaders.add($block))#end#if($hasHeaders.size()>0) #panelheader('Table of Contents') {{box cssClass="sidetoc"}}{{toc/}}{{/box}}#end{{/context}}{{/velocity}}

Поясню для тех, кто только начал знакомство с данной Вики.

В Xwiki для автоматизации используется различные средства автоматизации и одно из них Appache Velocity. В данном случае весь код между тегами {{velocity}} {{/velocity}} будет обрабатываться как код на данном языке шаблонов.

В макросе {{context}} мы указываем контекст для которого будет выполнятся наш код.
В нашем случае это контекст основного содержимого страницы. Таким образом, наш скрипт будет думать, что он не внутри сквозной боковой панели, а внутри блока с текстом статьи. Это необходимо для того, чтобы получить заголовки из которых формируется оглавление.
блок
#if($hasHeaders.size()>0)
#panelheader('Table of Contents')
#panelheader('Table of Contents') {{box cssClass="sidetoc"}}{{toc/}}{{/box}}
#end
Выводит нам заголовок для панели и сами ссылки на разделы статьи, только в том случае если на странице есть заголовки из которых можно собрать оглавление.
Макрос {{toc/}} - непосредственно создает оглавление. Мы обрамим его в макрос
{{box cssClass="sidetoc"}}, чтобы иметь возможность удобной стилизации блока. Но об этом немного позже.

Теперь необходимо вставить нашу панель в верстку страницы.
Я решил разместить блок слева.
Чтобы сделать также в админ-панели перейдите на страницу Мастер панелей -> вкладка "Список панелей" и просто перетащите панель с названием SideTOC на панель слева (справа).
Если перетаскивание не сработает, вы можете добавить панель в ручную
На вкладке "Макет страницы" в поле "ПАНЕЛИ СЛЕВА" (или справа) добавив "Panels.SideTOC".
например, Panels.Applications,Panels.Navigation,Panels.SideTOC

Не забудьте нажать кнопку "Сохранить".
Выглядеть будет примерно так:

На странице без заголовков блок не будет видно.
Я специально сделал заголовок "Основы" заголовком второго уровня, чтобы показать уровни вложенности.
Возможно вы захотите немного изменить внешний вид панели, тогда вернемся к её редактированию.

Но прежде убедимся, что у нас включен расширенный режим редактора.
Перейдите на страницу вашего профиля. Нажмите кнопку "Редактировать"
В разделе "Настройки" найдите пункт "Тип пользователя" и выберите значение : "Продвинутый" (Advanced). Теперь нам точно будет доступен редакторов объектов.

Откройте страницу созданной ранее панели, вы можете найти её на странице списка панелей или просто перейдя по адресу {домен}/bin/view/Panels/SideTOC.
Теперь у кнопки "Редактировать" доступен список с дополнительными вариантами.
Выберите пункт "Объекты".

В поле "Новый объект" выберите StyleSheetExtension и нажмите кнопку "Добавить"

Xwiki очень функциональна и позволяет поменять css стили практически для любого элемента. В данном случае мы поменяем стиль класса siidetoc, который был указан в макросе {box}.
Введите любое название например sidetoc, а затем CSS код:

.sidetoc {  border:0px;  margin:0px;  padding:0px;  width:100%;}.sidetoc ul {  padding-left:2px;  list-style-type:disc;  font-size:1em;  padding:0px;  margin-left:0px;}.sidetoc li {  padding-left: 0px;  margin-left:5px;  list-style-type:disc;}

В поле "Использовать это расширение" обязательно выберите "В этой вики" ,

Не забудьте сохранить страницу.
Проверяем нашу главную.
Теперь панель выглядит немного по другому:

Если сходу не нашли 10 отличий, то был добавлен буллет у записей второго уровня и немного изменены отступы.

Миссия выполнена можем переходить к следующему пункту.

Cвоя панель навигации справа / слева

Предположим, что стандартное меню навигации нас не устраивает и мы хотим сделать отдельную панель для очень важного раздела "Моя любимая пицца".
Для начала создадим сам раздел. Пусть он будет в корневом уровне сайта.
Перейдите на главную страницу и нажмите кнопку "Создать".
Введите название и какое-нибудь содержимое в редакторе. Затем аналогичным образом, создайте еще пару дочерних страниц.

Сейчас информация о нашей любимой пицце отображается в разделе "Навигация".

Мы хотим убрать эти страницы из раздела "Навигация" и перенести в свою собственную панель.
Для начала уберем ссылки на пиццу из стандартной панели навигации.
В админ-панели откройте раздел "Настройки интерфейса" - > "Панель навигации".
Перетащите раздел "Моя любимая пицца" в раздел "Исключенные страницы".

Теперь перейдите в соседний раздел "Меню" и нажмите кнопку "Добавить новую запись".
Введите название панели, например, PizzaMenu.
Удаляем заглушку. Если у вас WYSIWIG редактор нажмите кнопку "Источник" и вставьте следующий код:

{{documentTree root="document:xwiki:Моя любимая пицца.WebHome" compact="true"/}}

Ну или вы можете просто вставить макрос "Дерево страниц" и добиться также настроек.

В поле "root" первая половина значения - document:xwiki: - это особенность структуры адресов Xwiki, Вы со временем разберетесь в тонкостях, а вот вторую часть: "Моя любимая пицца.WebHome", можно легко узнать перейдя на страницу "Моя любимая пицца.WebHome" и открыв внизу вкладку "Информация".

В поле "МЕСТО ОТОБРАЖЕНИЯ МЕНЮ" выберите - "Внутри левой панели".
В поле "ОБЛАСТЬ ВИДИМОСТИ МЕНЮ" выберите - "Current Wiki".
Не забудьте сохранить.

Боковые панели к сожалению, не включатся автоматически, их надо добавить вручную.

Перейдите на страницу Админ-панель -> Мастер панелей.
И добавить в левую панель строку: Menu.PizzaMenu.WebHome

Например, вот так:

Сохраняем и наслаждаемся меню (откройте главную страницу чтобы проверить).

Осталось немного навести марафет.

Давайте заменим заголовок панели.
Перейдите на страницу меню. Через админ-панель или просто по адресу:{домен}/bin/view/Menu/PizzaMenu/

Аналогично прошлому разделу откройте редактор объектов.
Разверните "UIExtensionClass" и в тег {{menu}} добавьте: id="PizzaMenu".
Замените значение в "#panelheader("PizzaMenu"), на то что вам больше по душе. Например так:

Если хотите можете аналогично примеру с оглавлением подредактировать CSS стиль блока (именно для этого мы и добавили id="PizzaMenu").
Создайте объект для настройки стилей и введите:

#PizzaMenu ul.jstree-children{  padding-left:0px !important;}

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

Добавляем свои советы в панель подсказок

В самом верху справа у нас есть панель случайных подсказок. Допустим мы решим добавить туда несколько своих советов на русском языке.

Для этого надо в любом месте создать страницу.
Я создам пустую страницу Tips в разделе Xwiki чтобы она не "мозолила" глаза.

Откройте редактор объектов и добавьте объект расширения интерфейса.

В поле "Extension Point ID" вставьте: "org.xwiki.platform.help.tipsPanel".
В поле "Extension ID" введите любое название, например, "grammarHelp".
В поле "Extension Scope" выберите "Current Wiki".
В поле "Extension Parameters" введите:

tip = Чтобы воспользоваться исправлением опечатки нажмите Ctrl+ПКМ

Аналогичным образом создайте на странице еще одно расширение. См. скриншот.

Остается только сохранить изменения и дождаться появления советов.

Если честно я хотел добавить еще примеров, но статья итак получилась объемной.
Впереди у нас интеграция с Figma, GitLab, Swagger и кастомные DocumentThree!
Постараюсь не затягивать со следующим материалом.

Несколько лет назад я услышал от одного коллеги историю. Он в то время работал начальником отдела технической документации в IT компании. Дело было на собрании, посвященном знакомству с новым техническим директором. Тот, пожав моему коллеге руку и узнав о его роли, пошутил: Документация? Так ее же не читает никто! Двадцать первый век на дворе.

Вряд ли кому-то из нас было бы приятно оказаться на месте этого человека. Но, коллеги, положа руку на сердце, нет ли в подобном отношении нашей вины? К сожалению, я нередко сталкиваюсь с ситуациями, в которых документация, официальная или нет, не может мне помочь. А ведь ее кто-то писал, тратил время и усилия. Зачем это было сделано? И как можно сделать лучше? В этой статье я поделюсь своим видением того, как писать документацию, приносящую реальную пользу читателям.

Возможно, что-то из того, что написано в моей статье, покажется вам капитанским. Ничего страшного! Это значит, что вы уже владеете лучшими практиками написания документации. Статья в первую очередь адресована людям, недавно пришедшим в профессию, поэтому, коллеги, если я что-то упустил, или если у вас есть свой взгляд на вещи пожалуйста, отпишитесь в комментариях.

Что такое хорошая документация?

Итак, начнем. Что же вообще такое хорошая документация? Подробная? Или написанная с юмором, чтобы было не скучно читать? Для кого-то самая лучшая документация толстый том, который можно подложить под ножку стола, чтобы не шатался. На мой взгляд, хорошая документация такая, которая выполняет свою задачу.

А в чем задача документации? Ответов на этот вопрос может быть много. Документация может использоваться для обучения, для справки, или даже служить своего рода рекламой. Я слышал от коллеги историю о том, как менеджер по продукту просил ее написать документацию для нового продукта за три дня, делая упор на том, что все равно какую, ее никто читать не будет, она нужна только чтобы проект сдать. И это тоже задача, хоть и очень грустная.

В Plesk основная задача документации помогать клиентам самостоятельно решать проблемы, возникающие при использовании продукта, тем самым снижая нагрузку на техническую поддержку. Если клиент, столкнувшись с проблемой, смог решить ее при помощи документации и не завел тикет, значит, задача документации выполнена.

Хорошо, допустим. А что позволяет документации выполнять задачу? Какая она, хорошая документация, и как ее создавать? Есть ряд практик, которым мы следуем, когда пишем документацию в Plesk, и сегодня я хотел бы о них рассказать. Итак...

Хорошую документацию легко найти

Времена, когда лежащий в коробке с программой мануал был единственным источником информации для пользователя, ушли безвозвратно. В наши дни каждый имеет доступ к практически неограниченному количеству информации, и у технических писателей больше нет монополии на внимание пользователя. Как бы ни была хороша ваша документация, если она занимает низкую позицию в выдаче поисковых систем, ее просто никто не прочтет. Чтобы ваша документация приносила пользу, позаботьтесь о ее находимости (findability).

Более половины трафика нашего портала документации приходит из органического поиска. Вот как мы представляем себе сценарий, в результате которого пользователь (возможно) открывает нашу документацию:

1. Человек начинает пользоваться Plesk.

2. Человек сталкивается с затруднением.

3. Человек пытается разобраться с затруднением самостоятельно.

4. Когда желание преодолеть затруднение пересиливает нежелание тратить время на поиск помощи, человек вводит запрос в Google и открывает первую ссылку в выдаче.

Замечу, что по данным Google Search Console запросы пользователей не включают слово документация. Люди ищут plesk login, plesk install, plesk ftp и так далее. Скорее всего, запросы, по которым пользователи находят документацию вашего продукта, выглядят похоже. Чтобы пользователям было проще найти вашу документацию, важно использовать те термины и формулировки, которые они используют. Это особенно важно в случае если поисковая система на вашем сайте документации не очень хорошо производит нечеткий поиск.

Раз уж мы заговорили о находимости, я хотел бы также познакомить вас с терминами информационное фуражирование и информационный запах. Поведение человека, ищущего информацию, похоже на поведение зверя в поисках пищи. Зверь хочет получить максимум калорий, затратив минимум сил. Разыскивая пищу, зверь полагается на запах, который говорит ему, насколько велики шансы найти пропитание там, где он сейчас находится.

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

Как же привлечь внимание пользователя за те десять секунд, что у нас есть? Отличная практика разместить в самом начале каждого раздела краткое (не больше трех-четырех предложений) описание его содержания, в идеале оформив его так, чтобы оно визуально отличалось от остального текста и бросалось в глаза. Сюда же можно добавить ссылки на схожие по смыслу разделы, чтобы облегчить дальнейший поиск пользователям, оказавшимся не там, где они планировали. Вот как может выглядеть такое описание:

В этом разделе вы узнаете, как создать новый FTP аккаунт в Plesk. Если вы хотите узнать, как изменить логин или пароль существующего FTP аккаунта, пройдите по ссылке.

Благодаря этой секции попавший на эту страницу пользователь сможет быстро сориентироваться и понять, содержит ли просматриваемый им раздел ответ на интересующий его вопрос.

Хорошую документацию легко понять

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

В работе я руководствуюсь высказыванием Антуана де Сент-Экзюпери: Совершенство достигнуто не тогда, когда нечего добавить, а тогда, когда нечего убрать. Когда готов первый черновик документации для новой фичи, первое, на что я смотрю можно ли сделать текст проще и короче. Что помогает в этом?

• Часто употребляемые слова. Избегайте канцелярита, не пишите произвести манипуляцию с элементом управления когда хотите сказать нажать кнопку.

• Простые предложения.

• Короткие (4-6 предложений) абзацы.

Впрочем, здесь же я хочу упомянуть и еще одно правило, которым руководствуюсь: Пиши так коротко, как возможно, но не короче. Не нужно выплескивать ребенка вместе с водой и приносить полноту и ясность в жертву краткости.

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

Что еще можно сделать, чтобы ваша документация стала проще для понимания? Соблюдать меру при использовании вспомогательных средств, таких как снимки экрана, графики, таблицы и видео. Все они помогают нам донести до читателя информацию и сделать ее более наглядной, но перенасытить ими документацию так же просто, как пересолить суп.

Некоторое время назад я искал технического писателя в свою команду. В тестовом задании, предлагавшемся соискателям, была просьба написать короткую инструкцию, объясняющую, как установить расширение в Chrome. Один из кандидатов снабдил каждый шаг полноразмерным снимком экрана, что раздуло небольшую инструкцию на пару страниц. Чем это плохо? Напомню, что попадая на новую страницу, человек не начинает вдумчиво читать, он пробегается по ней глазами. Большой объем вкупе с обилием иллюстраций отпугивает, несложная процедура кажется чем-то сродни запуску ядерного реактора. Сложилось ощущение, что у соискателя были какие-то установки ("снимки экрана это хорошо"), но не было понимания, что любым инструментом нужно пользоваться к месту и в меру. Отбор он не прошел.

Хорошая документация описывает сценарии

Классический подход к документированию интерфейсов подразумевает последовательное описание индикаторов и элементов управления, размещенных на том или ином экране. Типичный пример снимок экрана с цифрами-выносками, а под ним нумерованный список, перечисляющий все, что пользователь и так видит. Введите имя пользователя в поле Имя пользователя. Нажмите Ok, когда захотите закончить операцию.

Проблема этого подхода в том, что он не отражает то, как люди пользуются документацией. Если когда-то и были времена, в которые человек, купив программу, внимательно читал от корки до корки лежащий в коробке мануал, они остались в прошлом. Никто не читает документацию, чтобы узнать, что делают все кнопки на экране Создать домен. Пользователи обращаются к документации, когда у них возникают затруднения с выполнением какого-то реального сценария, связанного с использованием продукта (создать почтовый ящик, защитить сайт SSL сертификатом, и так далее).

В свете этого, когда пользователь обращается к документации, написанной с использованием классического подхода, ему приходится конструировать процедуру самостоятельно, зачастую из информации, разбросанной по разным разделам. Хмм, наверное, мне нужно сперва сделать вот это действие, потом вот это, а затем вот это? И тут сразу возникают следующие проблемы:

• Пользователю приходится тратить время и усилия на то, чтобы сконструировать процедуру.

• Сконструированная пользователем процедура может быть неполной или вовсе неверной.

• Каждому пользователю приходится конструировать процедуру самостоятельно. Таким образом, чем больше у вас посетителей, тем больше времени они совместно потратят.

• Если сценарий не очень частый, пользователю, возможно, придется вернуться к нему через продолжительное время. К тому времени он может уже забыть о том, как выполнять нужную процедуру, и ему потребуется конструировать ее заново.

Всех этих проблем можно избежать, применяя сценарный подход к написанию документации. Это подразумевает, что вместо описания всех элементов интерфейса и их свойств, вы описываете последовательность действий, которые необходимы для выполнения того или иного реального сценария. Например:

• Как мне создать почтовый ящик?

• Как мне поменять пароль?

• Как мне удалить базу данных?

Плюсы этого подхода в том, что, во-первых, такую документацию легче искать за счет использования названия сценария в названии раздела, а во-вторых, пользователю не нужно тратить время на конструирование процедуры, так как все необходимые действия (и только они) перечислены в документации.

Хорошая документация самодостаточна

При написании документации в Plesk мы руководствуемся принципом Every page is page one (EPPO) почерпнутым из одноименной книги Марка Бейкера. Чтобы понять его суть, давайте подумаем о том, как люди читают печатные книги, и как ищут информацию в Интернете:

• Человек, читающий печатную книгу, начинает чтение с первой страницы и читает последовательно, постепенно создавая контекст. В пятой главе нет нужды расшифровывать термин, с которым читатель познакомился во второй.

• В случае с документацией в Интернете, любая страница может стать первой, так как пользователи приходят по ссылкам. Мы не можем контролировать то, где они окажутся, и мы не можем предполагать, что у них есть некий определенный контекст.

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

Приведу пример. Некоторое время назад для того, чтобы защитить сайт SSL сертификатом, нужно было выполнить в панели Plesk следующие действия:

1. Сгенерировать запрос на подпись сертификата (certificate signing request) и купить сертификат в центре сертификации (certificate authority).

2. Загрузить полученный сертификат в хранилище.

3. Выбрать загруженный сертификат в настройках веб сервера.

Номинально, каждый из приведенных выше пунктов можно рассматривать как отдельный сценарий, но подобный подход может ввести пользователя в заблуждение, так как для достижения цели (сайт защищен SSL сертификатом) нужно выполнить все вышеприведенные действия в правильной последовательности.

В согласии с принципом EPPO, нужно либо объединить все необходимые процедуры в один раздел, либо сделать несколько разделов, связав их ссылками. Например, в начале раздела, описывающего сценарий загрузить полученный сертификат в хранилище в Plesk нужно сослаться на раздел о сценарии сгенерировать в Plesk запрос на подпись сертификата, а в конце на раздел о том, как выбрать загруженный сертификат в настройках веб сервера. Благодаря этому, где бы посетитель ни оказался, он сможет сориентироваться, пройти сценарий от начала до конца и добиться желаемого результата.

Хорошая документация достоверна

Иными словами, она точно отражает то, как продукт выглядит и работает прямо сейчас, а не полгода назад. В наше время SaaS-продуктов, коротких релиз циклов и принудительных автоматических обновлений это правило, к сожалению, нарушается все чаще. Как ни странно, этим нередко грешит документация гигантов индустрии, таких как Microsoft или Google.

Думаю, не нужно объяснять, почему это вдвойне плохо, когда официальная документация содержит недостоверные сведения. Логотип компании на странице документации внушает уверенность, и посетитель тратит время попусту, пытаясь найти кнопку, которую убрали из интерфейса три релиза назад. Когда он понимает, что инструкции неверны, это действует как ушат холодной воды на голову и подрывает доверие и к документации, и к продукту, и к бренду. Единожды солгавший, кто тебе поверит?

Для того, чтобы подобного не происходило, команда технических писателей должна иметь следующее:

• Выстроенные процессы, позволяющие получать информацию обо всех влияющих на опыт пользователя изменениях в продукте до того, как они станут доступны публике.

• Достаточно ресурсов, чтобы своевременно отражать эти изменения в документации.

• Механизм сбора обратной связи, который позволит получать сигналы о тех неточностях, которые закрались в документацию несмотря на два предыдущих пункта. В Plesk мы получаем такую обратную связь от инженеров технической поддержки, а также от самих пользователей благодаря нашей форме обратной связи.

Хорошая документация пишется для определенной аудитории

Еще одно явление, о котором нужно знать, чтобы писать хорошую документацию это проклятие знания (curse of knowledge). Под таким зловещим именем скрывается когнитивное искажение, заключающееся в том, что человеку информированному сложно встать на место человека неосведомленного и увидеть ситуацию его глазами. Если вы когда-нибудь произносили или думали про себя Ну-у, да это все знают, вероятно, вы были под воздействием этого искажения.

К счастью, с этим искажением можно справиться. Достаточно помнить о нем и знать, кто целевая аудитория документации, которую вы пишете, и каким багажом знаний обладает ее среднестатистический представитель. Например, если вы документируете клиент Git, можно предположить, что представителю целевой аудитории не нужно рассказывать, что такое система управления версиями или как сделать коммит, но стоит задокументировать, как настроить доступ в репозиторий по SSH ключу. А если у вас в голове возникает мысль Это, наверное, всем известно, напомните себе, что вы пишете документацию не для всех, а для конкретной аудитории с конкретными знаниями и потребностями.

Проиллюстрирую этот пункт следующим примером: несколько лет назад я получил обратную связь от двух разных пользователей на один и тот же раздел. Она звучала примерно так:

• Пользователь А: Что вы пишете, как для дураков? Разжевываете вещи, которые любому известны!

• Пользователь Б: Вы знаете, не каждый из нас гений. Пожалуйста, пишите яснее, мне ничего не понятно.

Как вы думаете, кто из них был прав? На самом деле, правы оба. Судя по всему, раздел, на который они жаловались, как раз и был написан для всех, но в итоге не смог сослужить службу никому. Он был слишком сложен для новичка, но не содержал подробностей, интересных эксперту. Как избежать подобных ситуаций? Знать, кто целевая аудитория, и писать с учетом ее потребностей. Ничего страшного, если вы получаете обратную связь только одного типа (слишком сложно или слишком просто) это означает, что жалуются люди, не входящие в ЦА (конечно, если подобных обращений не десять штук за неделю).

Хорошая документация оказывает поддержку

Один из верных признаков плохой документации она разжевывает очевидное, но не оказывает поддержки там, где это нужно. Не всегда достаточно просто перечислить шаги, которые необходимо пройти для достижения цели. Если в процессе того или иного сценария пользователю нужно сделать выбор, последствия которого не каждому могут быть очевидны, документация может и должна облегчить принятие решения, дав дополнительную информацию. Это называется "помощь в принятии решения" (decision support).

Приведу пример. В Plesk для защиты от спама используется программа под названием SpamAssassin. Одна из доступных пользователю настроек (spam filter sensitivity) управляет тем, насколько строго фильтр отсеивает входящие письма с подозрением на спам. Работает она просто: пользователь задает значение, выраженное положительным числом не больше 127. Чем меньше число, тем строже фильтр. Вот как могла бы быть описана эта настройка в плохой документации:

Введите желаемое число в поле Spam filter sensitivity и нажмите Ok.

Технически вышеприведенная инструкция верна, но практически от нее мало пользы. Пользователь, не знакомый с работой SpamAssassin, не знает, какое число он может ввести и как это повлияет на работу фильтра. Как можно было бы сделать лучше?

Введите желаемое число (больше 0 и не больше 127) в поле Spam filter sensitivity и нажмите Ok. Чем меньше число, тем меньше вероятность того, что в ваш ящик попадет спам, и тем больше вероятность ложного срабатывания, и наоборот.

А можно ли сделать еще лучше? Как насчет такого:

Введите желаемое число (больше 0 и не больше 127) в поле Spam filter sensitivity и нажмите Ok. Чем меньше число, тем меньше вероятность того, что в ваш ящик попадет спам, и тем больше вероятность ложного срабатывания, и наоборот. Рекомендуемое значение 7, оно обеспечивает надежную защиты от спама с минимальной вероятностью ложного срабатывания и подойдет большинству пользователей.

Третий вариант дает пользователю информацию, необходимую для принятия информированного решения, а также подсказывает оптимальный вариант для тех, кто не может или не хочет принять решение сам. Безусловно, информация, призванная помочь в принятии решения, делает раздел длиннее, поэтому вам решать, где нужно подстелить соломки, а где все и так очевидно (конечно, не забывая при этом о проклятии знания).

Как еще можно облегчить жизнь пользователя? Не превращать его в Буриданова осла. Если продукт позволяет добиться того или иного результата несколькими путями, я не описываю их все. Я выбираю оптимальный (самый простой, самый быстрый и так далее) и рассказываю только о нем. Если же между этими путями есть разница (скажем, один быстрее, но подразумевает действия, требующие технических навыков или потенциально рискованные, например, выполнение запросов INSERT или UPDATE в базе данных), я описываю все варианты, эксплицитно указывая на различия между ними, чтобы помочь пользователю выбрать оптимальный для него вариант.

Ну и, конечно же, не забудьте предупредить пользователя в случае если его действия могут привести к неочевидным последствиям, особенно если они необратимы. Нет нужды писать о том, что удалить домен можно при помощи кнопки Удалить домен. Это очевидно. Что не очевидно, так это то, что при удалении домена, например, будут автоматически удалены и все резервные копии, или что пользователь лишится доступа в панель, если его учетная запись заблокирована. Налево пойдешь коня потеряешь куда полезнее и информативнее, чем просто поворот налево.

Заключение

Теперь вы знаете, как писать хорошую документацию по версии Plesk. Прежде чем откланяться, я хотел бы рассказать еще об одном принципе, который я также позаимствовал у Марка Бейкера. Он звучит просто Напиши одну хорошую страницу (Write one good page). Почему он кажется мне очень важным: если у вас уже есть массив документации, написанный по старинке и не соответствующий лучшим практикам, велик соблазн опустить руки. Переписать все с нуля это целый подвиг! У нас нет столько времени и ресурсов! Но это не обязательно.

Наверняка среди вашей документации есть более посещаемые разделы и менее посещаемые (а если вы не знаете, сколько посетителей читает вашу документацию, то это отличный повод настроить веб аналитику). Переработайте ваш самый посещаемый раздел. Проследите за реакцией пользователей. Сделайте выводы, внесите коррективы, возьмитесь за второй по популярности раздел. И, возможно, пожимая вам руку, новый технический директор скажет Документация? Это же очень важно! Загляну к вам в три часа, хочу узнать, как вы работаете.

Спасибо за внимание!

P.S. Хочу сказать Спасибо! моим коллегам Катерине Говердовской и Владимиру Головизнину за помощь в подготовке статьи.