Управление знаниями: какие документы нужны и что в них фиксировать

[astenix]

Чем этот текст не учебник?

[reinvent]

В каком смысле у документа нет автора? Каждый пишет, что хочет, и неясно, кто написал?

[nerazzgadannaya]

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

[reinvent]

Тогда кто-то по идее должен быть хотя бы модератором

[powerman]

В этом нет реальной необходимости. Наоборот, свобода редактирования помогает улучшить понимание документа читателями.

Обычно такие требования — наличия явного автора или модератора — возникают от страха, что в документ "попадёт фигня", в связи с чем он потеряет ценность и даже начнёт вредить. Но фишка в том, что если кто-то добавит в документ фигню, то это скорее хорошо, нежели плохо — это будет чётким сигналом того, что эта фигня находится в голове (как минимум одной), и что текущий текст документа не был достаточно ясен, чтобы такая фигня в голове вообще не возникла (для чего обычно документы и пишут). Заинтересованные лица (подписанные на получение уведомлений при изменении этого документа) обычно сразу среагируют на такое некорректное изменение документа, обсудят с автором последней правки почему он написал фигню, и постараются подправить документ так, чтобы не просто убрать эту фигню, но и прояснить дополнительно этот документ, чтобы уменьшить вероятность что та же фигня придёт ещё в чью-то голову.

[reinvent]

Таки есть авторы правок. Тогда понятно.

[reinvent]

Чтобы заинтересованные лица среагировали, должна быть определенная культура правок, как мне кажется. А то один понадеется на другого, а другой напишет коммент «дурь» или удалить без пояснений.

[powerman]

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

Чтобы они среагировали достаточно двух вещей: работающего механизма уведомления о правках, и наличия заинтересованности в корректности документа.

Если писать "дурь" или удалять — причём без пояснений, то это приведёт только к тому, что это придётся делать снова и снова, поскольку без пояснений не была выявлена и исправлена причина некорректной правки. Либо к тому, что документом перестанут пользоваться, считая его некорректным с одной стороны, и не имея возможности исправить его с другой. В общем, когда люди заинтересованы в наличии корректной документации — они так не делают.

[nerazzgadannaya]

Ну я бы исходила из предположения, что в айти компаниях работают взрослые люди, культура правок формата — не удаляй всуе и не пиши «дурь» в комментах, кажется, часть common sense, а вот повести какую-то горячую техническую дискуссию с правками — это сделает артефакт знания только лучше. Также, как в код ревью это работает.

При этом, я согласна с тезисом, что должен быть у каждго артефакта maintainer, тот кто примет конечное решение, будет собирать комментарии и делать действия по ним и, если что, откатит к предыдущей версии.