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


Видео выступлений:


SECR-2017: "Единый источник в документации: подходит вашей команде или нет?" 2017.secr.ru/program/submitted-presentations/singl... (длительность 12 мин.).


Круглый стол SPB SPM Meetup #55 "Документация в проекте: польза или затраты" https://www.youtube.com/watch?v=Ju15UYIpnJo (длительность 1ч. 40 мин.)
Контакты
Местоположение
Россия, Санкт-Петербург и область, Санкт-Петербург

Достижения

Все достижения (2)

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

Все теги (45)

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

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

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

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

    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. Здесь вам лучше погуглить оптимальный вариант для предыдущих двух пунктов.
    Ответ написан
    Комментировать
  • В чем разница между Application Letter, Cover Letter, Motivation Letter?

    eduardtibet
    @eduardtibet
    Technical Writer / Documentation Engineer
    По сути это - одно и то же. Призвано показать, что вы:

    - не какое-то школоло, а взрослый муж, умеющий писАть :)
    - очень-очень-очень хотите в компанию.
    - компании очень-очень сильно повезет, если она возьмет вас.

    Примеров много в гугле.

    Если кратко план, то:
    1. Я такой-то такой.
    2. Нашел вас там и там.
    3. Хочу засвидетельствовать мое почтение.
    4. Я совершенно то, что вам нужно, т.к. я <спойлер: умею делать все то, что написано у вас в нетехнических требованиях>
    5. Краткое резюме в виде рассказа, но БЕЗ навыков. Закончил такой-то институт, у меня была прикольная диплоная работа, после диплома я пошел туда, где только набирался опыта, а потом туда, где опыт был востребован и мы делали такие супер-штуки, но там не сложилось, команду разогнали и я пришел к вам.
    6. В качестве приложения - см. мое резюме, где расписаны все скилы.
    7. С нетерпением жду от вас ответа.
    8. Засим откланиваюсь, <вы>.

    P.S. Что касается IT
    - здесь cover letter вам не нужны. Вас и так оторвут с руками (если, конечно, умеете ими что-то делать совместно с головой, конечно :)
    - там - нужны обязательно. Без этого - резюме просто выкинут в корзину (ну, если конечно, вы не супергуру, которого зовут на конфы и т.п.).
    Ответ написан
    2 комментария
  • Как автоматически создавать документацию к программному коду?

    eduardtibet
    @eduardtibet
    Technical Writer / Documentation Engineer
    добавлю к предыдущему комментарию

    "... и никакого ворда" :)
    Ответ написан
    1 комментарий
  • Какой ГОСТ применять?

    eduardtibet
    @eduardtibet
    Technical Writer / Documentation Engineer
    Артем

    Для АС применим ГОСТ 34.x серии. Ознакомьтесь с ним.

    Вам может быть полезна книга:

    "Вадим Глаголев Разработка технической документации. Руководство для технических писателей и локализаторов ПО. СПб, Питер, 2008." ISBN 978-5-388-00101-6 Там все о документации с точки зрения ГОСТов.
    Ответ написан
    Комментировать

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

Все вопросы (2)