Расскажите, а что вы используете?

Сейчас используем базу знаний на основе вики + пачку пдф ;) Думаем над док.порталом для конечных пользователей на базе Markdown (GFM, kramdown) + Jekyll (liquid, lunrjs, yaml) + Mercurial + Rsync (если будет нужно). Внутри - Confluence + кто на что гаразд (MS Office).

Стремлюсь исключить пдф как таковой, но если комуто понадобится, планирую конвертировать через pandoc с использованием латех-шаблонов

Коллеги, вижу у этого поста мало лайков.
Возможно вы не согласны? Или всё написанное - фигня полная? ) Дайте, пожалуйста, фидбэк

​​Документ готов, когда его начали дополнять

Продолжаю делиться идеями, добытыми на двух конференциях. Игорь Цупко, директор по R&D в компании Флант, так определяет definition of done для внутренней документации:

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

Если не дополняют — ищите причину:

— Документ не внедрён. Тогда нужно буквально пойти и внедрить. Поговорить с людьми, рассказать, продать. Это может занять гораздо больше времени, чем вам казалось, но пока документ не внедрён, выпускать его новую версию может быть бессмысленно.

— Люди не умеют/боятся пользоваться инструментами для дополнения документа. Да, так тоже бывает на ранних стадиях жизни. Каждого нужно провести за ручку или обеспечить механику, чтобы кто-то его проводил за ручку.

— Люди боятся вообще писать. Тогда нужно дать им в помощь писателя, чтобы тот оформлял их мысли.

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

— Документ никому не адресован.  Для работы с этим аспектом есть отличный инструмент — граф коммуникаций. Это ещё одно сокровище, добытое на конференции и о нём тоже будет отдельный пост.

---

Игорь пишет заметки о руководстве командой и управлении знаниями в @lovely_it_hell.

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

— Настолько доверяют писателю, что даже мыслей не возникает дополнить или переделать его работу😄 Ну или документ просто идеален, что нет смысла его дополнять, а писатель прям заинька-заинька😂

Ну это всего лишь моё скоромное мнение и хорошее настроение с утра, не более того))))

Документ описывает реальность. Реальность меняется.

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

Впрочем, может быть ещё документ о будущем. Как надо сделать. Но там та же история. Обычно проекты не реализуются точь-в-точь как было задумано. Будут новые подробности, задача немного изменится. Эти изменения должны отразиться в документе.

Согласна) У меня есть документ, который раз в 2 недели переписывается или дописывается, так как программисты чего-нить добавят/уберут итд итп...
Но есть же такие приложения, которые раз написались и больше не меняются, ну то есть нет новых версий/релизов , тогда один документ и не меняется годами. Вот тогда можно написать один раз, но оченьььььь хороший документ)

я понял, снова те же грабли.
я-то про внутреннюю документацию больше.

> definition of done для внутренней документации

Да нет в целом у вас все хорошо написано, правильно) В общем и целом я согласна, но есть какое какие исключения))))

у меня так часто

На тему PlantUML из канала. Для серверной версии конфлюенса есть бесплатный плагин для рисования таких диаграмм: https://marketplace.atlassian.com/apps/41025/plantuml-for-confluence?hosting=server&tab=overview

да, я им рендерю диаграммки графов на языке dot

хороший

У нас в конфлюенсе он тоже есть.

У меня скоро статейка выйдет про все популярные виды таких графиков\схемок