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

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

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

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

В заголовке использовано слово сложной, под которым можно понимать все, что угодно. Утверждение о том, что 2 * 2 = 4, если вдуматься, тоже очень не просто. Но в данном случае всё банальнее. Речь идёт о ЕСКД, ГОСТ, ОСТ и тому подобных скучных терминах, отягчаемых бюрократической процедурой согласования.

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

Сразу решили, что попробуем сделать документацию актуальной, т.е. обойтись без покраски травы в зелёный цвет. И сразу решили, что это будет Asciidoc. Почему? Потому что из текстовых языков разметки для подготовки документации он наиболее функциональный, а разворачивать неповоротливые DITA и Docbook не хотелось.

Пройдя определённую боль, мы с коллегами решили ей поделиться.

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

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

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

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

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

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

          - Да!

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

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

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

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

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

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

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

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

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

В первой статье мы поговорим о простых приемах настройки панелей в Xwiki.

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

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

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

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

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

Ждать долго не пришлось, при обновлении на сервере PHP c 7.2 до 7.4 - мы получили страницу с описанием ошибки, вместо документации. Ошибка найдена в библиотеке, которую мы использовали для рендеринга UI документации. ПР на гитхабе был создан быстро, но провисел в статусе open почти неделю. После этого, тикет насчет документации пошел в работу.

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

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

• Можно ли распознать вас на улице? И насколько автоматически/достоверно?
• Позавчера писали, что в Московском метро задерживают преступников, а вчера писали что в Лондоне не могут. А ещё в Китае распознают всех-всех на улице. А тут говорят, что 28 конгрессменов США преступники. Или вот, поймали вора.
• Кто сейчас выпускает решения распознавания по лицам в чём разница решений, особенности технологий?