Рады сообщить, что опубликована программа и открыта регистрация на Мини-Гипербатон про генерацию документациию в Москве и Санкт-Петербурге.

Мы также принимаем заявки на секцию блиц-докладов Lightning talks: рады будем узнать о вашем опыте генерации документации.

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

Всем привет, 

4 декабря в Москве и 11 декабря в Санкт-Петербурге состоится Мини-Гипербатон, посвященный генерации документации. Докладчики от Яндекса расскажут про Swagger/Open API. 

Мы принимаем заявки на Lightning talks (секцию блиц-докладов): будем рады послушать о вашем опыте генерации документации. 

Программу мероприятия и открытие регистрации мы анонсируем дополнительно.

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

Добрый день!

В нашей компании хотят перейти к единому источнику документации и внедрить подход Doc As Code.

Какие требования:

1. Хранить всю информацию в исходниках, написанных на легковесном языке разметки Asciidoc.
2. Хранить исходники в репозитории в Git.
3. Из исходников  создать html-файлы и разместить на сайт.
4. Собрать из нескольких исходников документ, применить к нему стили и сконвертировать в pdf. 

Какие трудности:

1. Нужен инструмент, который из исходников создаст html-файлы и разместит их на сайт.
2. Нужен инструмент, который сможет по тегам найти в репозитории определённые исходники и собрать из них документ.  
3. Нужен инструмент, который к собранному документу применит стили (заранее подготовленный шаблон) и сконвертирует его в pdf.

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

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

С уважением, Эльвина

Всем привет, 

Опубликована программа Седьмого Гипербатона, который состоится 25 мая в Москве.

Докладчиками на конференции выступят сотрудники компаний Яндекс, DevExpress, ГК «Доброфлот», Лаборатория Касперского, Intento, Alef Development.

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

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

Всем привет, 

Рады сообщить, что открыта регистрация на Седьмой Гипербатон. Мероприятие состоится 25 мая в Москве.

В этом году мы поговорим об организации процессов разработки и актуализации документации в производственных компаниях, сложностях, возникающих при миграции больших массивов документации в случае изменения инструментов документирования, языках облегченной разметки и документации на open-source продукты, управлении внутренними знаниями в компании. Обсудим опыт организации процессов локализации в разных компаниях и посмотрим на доменно-адаптивные движки переводов. В программе примут участие спикеры от компаний Яндекс, DevExpress, ГК «Доброфлот», Лаборатория Касперского, Intento.

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

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

Всем привет,

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

Мероприятие пройдет в московском офисе Яндекса с онлайн-трансляцией для участников из других городов.

О публикации программы и открытии регистрации напишем дополнительно.

Да пребудет с вами Сила!

4 апреля в 11:00 мы в штаб-квартире «Лаборатории Касперского» проведем конференцию для технических писателей, редакторов, локализаторов и всех, кто работает с техническими текстами. Сквозной темой конференции станет качество: текстов, коммуникаций и процессов создания документации.

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

Подробности и регистрация: 
https://kas.pr/procontent2019

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

1. Изменение структуры бокового меню

Структуру сайдбара (боковое меню слева на страницах wiki-сайтов) можно менять на странице MediaWiki:Sidebar – просто править ее в wiki-редакторе, придерживаясь синтаксиса:

  * <название блока 1>
  ** <ссылка 1>|<отображаемый текст 1>
  ** <ссылка 2>|<отображаемый текст 2>

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

2. Загрузка файлов различных форматов

По умолчанию в виде файлов можно загружать только png, gif, jpg, jpeg, webp. Список возможных расширений можно расширить в файле LocalSettings.php в строке:

  $wgFileExtensions = [ 'png', 'gif', 'jpg', 'jpeg', 'webp' ];

Нужен админский доступ к этому файлу. Для ведения документации в Wiki мне лично не хватает загрузки по крайней мере файлов с такими расширениями: docx, pdf, svg, bpmn, zip.

3. Использование принципа единого источника

Этот принцип практикуется в «продвинутых» относительно Word технологиях создания документации (DocBook, DITA...) и заключается в том, что повторяющийся один и тот же блок данных (тест, картинки...) хранится в одном(!) месте и подтягивается в разные документы спецкомандами.
MediaWiki имеет функционал шаблонов, который поддерживает данный принцип.
Создается страница, например, Шаблон:Todo. Потом в разных статьях в редакторе пишется {{Todo}} и в это место при отображении в браузере Wiki вставляет содержимое вышеприведенной страницы.
В шаблонах можно задавать места для параметров, например {{{par}}}, а при вызове параметру присваивать значение, например, {{Todo|par=Абракадабра}}. Такие плейхолдеры полезны для другой отличительной особенности «продвинутых» технологий – когда требуются минорные изменения шаблона на лету в зависимости от того, в какой документ вставляется шаблон.
Специального доступа к шаблонам в Wiki не требуется.
Можно вставить в страницу_1 содержание страницы_2 и без шаблонов: {{:страница_2}}.

4. Подсветка синтаксиса программного кода

Есть варианты:

1. SyntaxHighlight – расширение для MediaWiki, которое нужно подключить.
2. HIGHLIGHT.JS – библиотека JS+CSS для подсветки кода различных языков. Подключается ссылками на js и css файлы (или на cdn сервере, или на скачанные). Есть неплохая подсветка XML. Выбор стилей подсветки. Чтобы разместить js, css на сервере (в виде файла или в БД) нашей Wiki и включить их в шапку страниц Wiki требуется администратор.

5. Конвертация wiki-разметки

Word ➞ Wiki (варианты):

1. Есть некоторое расширение Word2MediaWikiPlus.
2. Экспортировать из Word файл docx в mht (вебстраница в одном файле). Потом открыть в браузере и скопировать в буфер обмена. Потом вставить в новую страницу Wiki в визуальном редакторе. Картинки при этом надо будет загрузить и прописать отдельно. Примечания также оформить отдельно.
3. В Word выделить текст и скопировать в буфер обмена. В визуальном редакторе Wiki вставить из буфера. Результат есть, но придется с форматированием чуть больше повозиться.

Excel ➞ Wiki:

   Сохранить лист книги в веб-страницу mht. Открыть в браузере. Выделить всё (Ctrl+A). Скопировать в буфер обмена. В визуальном редакторе Wiki вставить из буфера.

Wiki ➞ Word (варианты):

1. Расширение DocExport позволяет выкачать любую страницу вики в формате MS Word.
2. Скопировать из Wiki в буфер обмена и вставить в Word.

Wiki ➞ PDF:

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

6. Другие полезные фичи MediaWiki

Категоризация статей

Чрезвычайно полезная функция, которая позволяет маркировать статьи и загруженные файлы по темам. Для этого достаточно внизу статьи добавить строку [[Категория:Название_категории]]. Если статья принадлежит разным категориям, то маркировку для каждой категории нужно повторить.
В результате таких маркировок, во-первых, в Wiki будет существовать страница Категория:Название_категории со списком статей и файлов данной категории, во-вторых, на странице Служебная:Категории будет ссылка на категорию Название_категории. Данные служебные страницы по мере маркировок новых статей будут актуализироваться автоматически.
Возможна иерархия категорий, если страницу дочерней категории пометить кодом родительской категории.
Функция категоризации в совокупности с функцией загрузки и хранения файлов разных форматов позволяет с удобствами использовать движок в качестве хранилища документации.

Просмотр загруженных файлов по формату

Есть служебная страница Служебная:MediaStatistics. На ней аггрегируется статистика по количеству файлов определенного формата, загруженных в Wiki. Название формата в списке - это активная ссылка, которая ведет на страницу со списком файлов определенного формата. Если загружать файлы документации только в форматах PDF и DOCX, то это будет дополнительным удобным местом для знакомства с наполнением Wiki, которое касается документации. Если загружать схемы только в формате BPMN, то на этой странице их также будет удобно искать.
Если маркировать страницы загруженных файлов категорией, то на странице этой категории будет существовать обособленный раздел "Файлы в категории", что крайне полезно для нашей заявленной задачи.
Эта фича в совокупности с возможностью расширять список загружаемых форматов также является сильной стороной движка в использовании его в качестве файлового хранилища.

Сноски

Предустановленное расширение Cite позволит пользователю Wiki с удобством расставлять сноски по тексту, что особенно актуально и полезно в научных статьях, но также может пригодиться и в технической документации. Расширение хоть и поставляется с движком, находясь в папке extensions, но не активизировано в файле LocalSettings.php. Поэтому, в этом файле надо прописать:

wfLoadExtension( 'Cite' );

После этого в тексте в тех местах, откуда надо сослаться на источник/комментарий/примечание надо в коде страницы вставить <ref>Пояснение = текст сноски</ref>, а в конце страницы сделать вывод всех этих примечаний примерно так:

== Примечания ==
<references/>

В итоге в месте ссылки на сноску она будет выглядеть так: [2] и это будет кликабельная ссылка, которая будет перебрасывать читателя вниз в раздел Примечания и текст нужной сноски будет подсвечен. Тексты сносок в разделе Примечания будут также ссылками, ведущими на место сноски в тексте.

Подключать свои JS и CSS файлы

Это можно делать двумя глобальными способами:
1. Писать свой код на страницах MediaWiki:Common.js и MediaWiki:Common.css
2. Подключать js-скрипты и css-стили файлы в LocalSettings.php:

$wgHooks['BeforePageDisplay'][] ='onBeforePageDisplay';
function onBeforePageDisplay( OutputPage &$out, Skin &$skin )
{ # подключаем нужное в конец head
    $script = '
	<link rel="stylesheet" href="/resources/lib/hightlight-js/styles/solarized-dark.css">
	<script type="text/javascript" src="/resources/lib/hightlight-js/highlight.min.js"></script>
	<script>hljs.initHighlightingOnLoad();</script>
	';
    $out->addHeadItem("itemName", $script);
    return true;
};

В первом случае js и/или css код будет хранится в базе данных и из нее подтягиваться на каждую страницу. Во втором случае содержание переменной $string будет внедряться в область заголовка <head> каждой страницы.
Также для кастомизированных css-стилей есть расширение CSS (ссылка ниже), благодаря которому можно будет подключать css как для всех страниц Wiki, так и для отдельных.

Возможность вставлять на страницы видео- и аудио-ролики

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

1. Скачать архив с расширением;
2. Скопировать содержимое архива в папку /extensions и переименовать внутриархивную папку в EmbedVideo;
3. В файле LocalSettings.php прописать wfLoadExtension( 'EmbedVideo' );.

После этого форматы медиафайлов, прописанные в EmbedVideo.hooks.php, становятся разрешенными для загрузки в Wiki. И начинают действовать обработчики плейсхолдеров в коде wiki-страниц для вставки видео и аудио. Самый простой плейсхолдер: [[File:S1200.mp4]] вставляет видеоролик, который был загружен на сервер.

Кроме видеороликов, загруженных в локальную Wiki, расширение позволяет вставлять на страницу iframe с src на адрес видеоролика одного из популярных сервисов с помощью разнообразных плейсхолдеров. Доступные сервисы можно найти в файле VideoService.php и, по всей видимости, добавить свой сервис можно там же при достаточном знании PHP и регулярных выражений.

Поиск

На каждой странице Wiki вверху справа есть поле для поиска, которое удовлетворит 80% ваших запросов. Но в некоторых случаях этого недостаточно.

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

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

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

7. Выводы

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

Оригинал статьи здесь (это мой оригинал).

Всем привет, 

В преддверии мероприятия хотим поделиться ссылками на программу  Мини-Гипербатона про метрики эффективности:

• Москва
• Санкт-Петербург

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

Всем привет,

Рады сообщить, что открыта регистрация на Мини-Гипербатон про метрики эффективности в Москве и Санкт-Петербурге.

Программу мероприятия мы анонсируем дополнительно.

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

Всем привет,

Рады сообщить, что опубликованы материалы Шестого Гипербатона.

Видео

• Текст как данные: автоматизируем формирование контента — Михаил Острогорский, Философт
• Контент-стратегия: новый уровень экспертизы    — Елена Федотова, Intel Corporation
• Новый взгляд на документирование API и SDK в Яндексе — Юлия Пивоварова, Андрей Поляков, Яндекс
• Машинный перевод: опыт Яндекса — Ирина Рыбникова, Анастасия Пономарёва, Яндекс
• Ландшафт сервисов облачного машинного перевода — Григорий Сапунов, Intento
• Как работают разные инструменты автоматизации перевода и как их выбирать — Фёдор Бонч-Осмоловский, Левша

Фотографии в социальных сетях

• Facebook
• VK

Всем привет,

7 декабря в Москве и 13 декабря в Санкт-Перербурге состоится Мини-Гипербатон, посвященный метрикам эффективности документации.

Мы рассматриваем варианты расширения формата мероприятия, поэтому если вы хотите поделиться опытом оценки эффективности документации — пишите на yandex-techdoc@yandex-team.ru

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

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

Всем привет, 

Опубликована программа Шестого Гипербатона, который состоится 22 сентября в Москве.

Докладчиками на конференции выступят сотрудники компаний Яндекс, Философт, Intel Corporation, Intento и Левша.

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

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

Всем привет, 

Открыта регистрация на Шестой Гипербатон.

Мероприятие состоится 22 сентября в Москве.

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

Всем привет,

Рады сообщить, что 22 сентября в Москве состоится шестой Гипербатон. Будем рады видеть специалистов в области документирования и локализации.

В этот раз поговорим о контент-стратегии, метриках документирования, машинном переводе и многом другом.

О публикации программы и открытии регистрации напишем дополнительно.

Да пребудет с вами Сила!

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

Поделитесь опытом - кто какие метрики считает и какие выводы делаете на их основании?

В мае мы провели Мини-Гипербатон, посвященный текстовым редакторам. Мероприятие проходило в Москве и Санкт-Петербурге. 

Рады сообщить, что материалы с конференции опубликованы. 

Видео

• Hackable Text Editors — Михаил Гончаров, Яндекс
• Oxygen XML: почему и как — Юлия Кухмай, Алексей Замулла, Яндекс
• Per aspera ad astra: от неструктурированного контента к CMS —  Елена Федотова, Intel Corporation

Фотографии и видео в социальных сетях

• Facebook
• VK

Вопрос ! При приобретении Oxygen XML Editor в комплект включается DITA или ее нужно приобретать отдельно ? Если есть ссылки буду благодарен ))

Всем привет, 

Опубликована программа Мини-Гипербатона про текстовые редакторы:

• Москва: программа и форма регистрации.
• Санкт-Петербург: программа и форма регистрации.

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

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

Мини-Гипербатон — камерное мероприятие для обмена опытом на заданную тему с упором на живое общение, рассчитанное на небольшое количество участников. Чтобы встреча прошла наиболее продуктивно, отбор проводится с учетом опыта и интересов зарегистрировавшихся. После мероприятия мы выложим видеозаписи докладов.

Всем привет, 

24 мая в Москве и 25 в Санкт-Петербурге состоится Мини-Гипербатон, посвященный редакторам для работы с текстами.

На встрече поговорим о средствах для широкого набора исходных форматов, а также средах для работы с DITA-контентом.

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

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

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