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

Доклад на SECR-2017 "Единый источник в документации: подходит вашей команде или нет?": 2017.secr.ru/program/submitted-presentations/singl... (презентация доступна, видео выступления доступно здесь: 0x1.tv/20171021DH ).

Technical notes:

Area of expertise: Docbook/XML-based single sourcing technical documentation solutions.

Key points:
- Single sourcing technical documentation from scratch for IT/Telecom, Industry/Manufacturing, Publishing, Academics/e-Learning.
- Migrating existing technical documentation to single source.
- Multichannel publishing for different audiences/os/targets with reuse options.
- Diff|Merge tasks within distributed authors, variety of authoring tools on multiple platforms.
- External systems integration within single sourcing paradigm.
Контакты

Наибольший вклад в теги

Все теги (9)

Лучшие ответы пользователя

Все ответы (93)
  • Кто должен составлять документацию ( в компании) на программный продукт?

    eduardtibet
    @eduardtibet
    Technical Writer / Documentation Engineer
    В принципе, коллеги выше уже основную часть сказали. Добавлю от себя:
    1. Концепт системы и ТЗ - Аналитик.
    2. Планы работы и контроль их выполнения - ПМ
    3. Эксплутационная документация (руководства разного типа и вида, FAQ, HOWTO и т.п.) - технический писатель.
    4. API, SDK reference, архитектурные документы - либо технический писатель (если он высокого класса), либо разработчики.
    5. Постановка работ по документированию (типы документов, исполнители, docflow между членами команды и.т.п.) - в больших компаниях технический писатель уровня Lead. В маленьких стартапах - у кого больше опыта.
    6. Тест-планы, тест-кейсы - группы тестирования (либо лид, либо наиболее опытный)

    Для справки предыдущих участником треда: заказчики в 98% случаев НИЧЕГО не делают. Это правда жизни. Т.е. они скажут "хочу это и это", но построить из этих слов грамотную систему - см. п.1
    Ответ написан
  • Где сисадмину хранить документацию и конфиги серверов, а также собственные наблюдения и размышления?

    eduardtibet
    @eduardtibet
    Technical Writer / Documentation Engineer
    Отвечу по документации...

    1. Формат.
    Для вас лучше это делать в plain text, т.к. даже будучи в консоли, вы всегда сможете их прочитать.
    Форматы: любой из .md, .rst, asciidoc (т.к. есть возможость визуализировать из в pretty format) внутри различных систем.

    2. Хранение
    Способ хранения - только SCM (какой именно: git, svn, hg или более старое - не знаю, что вы используете). Поясню, почему не файловая система:
    - вам важно знать state вашего оборудования на определенный момент. Т.е. вы всегда можете посмотреть конфигурацию, актуальную месяц/два назад и выявить проблемы.
    - вы всегда можете сделать diff и посмотреть изменения. Часто, это должно быть сделано не просто сейчас, а "внезапно" :)

    Использовать atlassian confluence, как говорят выше, я для ваших задач НАСТОЯТЕЛЬНО НЕ рекомендую. Причина:
    - вы привязаны к вендору (даже за 10 баксов за мин. лицензию). Если вы откажетесь от вендора вы НЕ сможете выцепить ее - только copy/paste или покупкой плагинов за сотни баксов.
    - у атлассиана разметка жестко забита в софт. Там нельзя выгрузить wiki разметку (кроме как при покупке плагинов за сотни баксов, например, scroll)
    - и, самое главное, вам не просмотреть текст в консоли!

    3. Визуализация
    Здесь все зависит от количества времени, которое вы готовы потратить. Знаю, существуют решения для визуализации md для обычный wiki. Здесь вам лучше погуглить оптимальный вариант для предыдущих двух пунктов.
    Ответ написан
  • Как документировать существующее решение?

    eduardtibet
    @eduardtibet
    Technical Writer / Documentation Engineer
    Чтобы понять, какие решение вам надо, вам надо задать себе следующие вопросы:
    1. Предполагается ли документацию выносить наружу?
    2. В каких выходных форматах вы хотите поставлять документацию? Предполагается ли печатка (как класс)?
    3. Предполагается ли многоуровневая документация (т.е., например, несколько модулей для клиента А, несколько для клиента Б и т.п.)?
    4. Надо ли документировать API (руками или автоматически)?
    5. Кто будет осуществлять поддержку всего этого хозяйства?
    6. Какой объем (примерно) сейчас и какой объем будет после года?
    7. Надо ли хранить версионность всего этого добра?

    Есть еще вопросы, но на текущий момент пока хватит :)
    Ответ написан
  • Как создать корпоративный документ в Word?

    eduardtibet
    @eduardtibet
    Technical Writer / Documentation Engineer
    Если целевой документ не будет требовать редактирования ПОСЛЕ внесения информации о контрагенте, то оптимальной в вашем случае представляется схема:
    xml (c variable-данными) + xsl:fo (шаблон) > pdf (результирующий документ). В этом случае вы гарантированно получите результат, при котором документы будут отличаться только на величину содержимого xml-файла с данными.
    Ответ написан