В технической документации часто встречаются фразы с использованием страдательного залога. Параметры там «задаются», файлы «сохраняются», а программа «запускается». Ох, опасная эта форма для строгих и однозначных описаний! Почему же страдательный залог заставляет читателей страдать? Будем разбираться... Читать далее
У вас стоит задача интегрироваться с удалённым сервисом, который работает по ГОСТу и "только через КРИПТО-КОМ", а вы хотите использовать OpenSSL с gost? На форуме "Сигнал-КОМ" вы видите кучи сообщений, что "ключи из формата КРИПТО-КОМ нельзя конвертировать в формат OpenSSL-гост-совместимых"? На самом деле конвертация возможна. Читать дальше →
Продолжая тему использования Asciidoc (и других аналогичных форматов) для организации процессов непрерывного документирования, хочу рассмотреть тему автоматический генерации технической документации. Автоматическая генерация документации — распространенный, но очень расплывчатый термин. Я понимаю под этим термином извлечение для представления в удобном виде информации, содержащейся в исходном коде и настройках документируемой программы (информационной системы). Читать дальше →
Дисклеймер: это продолжение темы о составлении правильной технической документации. В первой статье мы рассказали, какие цели преследуются при составлении инфраструктурной документации и какие у нее особенности. А теперь поговорим о том, как составить годный стайлгайд, чтобы