Остерегайтесь управления документацией. Адская петля техлида.
documentation developer-productivity software-documentation technical-documentation software-documentation-tools documentation-tools how-to-write-documentation documentation-management

Остерегайтесь управления документацией. Адская петля техлида.

9 мая 2022 г.

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


Разберем это утверждение.


Кто отвечает за документацию программного проекта?


Когда дело доходит до документации, есть несколько возможных заинтересованных сторон:


  1. Разработчики

  1. Старшие разработчики

  1. Технические руководители

  1. Владельцы продукта

  1. Менеджеры проектов

У разработчиков есть самодокументирующийся код.


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


Часто задача написания документации ложится на:


  1. Технический руководитель

  1. Старший разработчик программного обеспечения

В первую очередь потому, что они знают ценность наличия хоть какой-то документации. Иногда это бизнес-требование, за которое они несут ответственность. Возможно также, потому что им приходится ежедневно отвечать на множество вопросов, и они действуют как ходячие базы знаний. Вместо того, чтобы отвечать на один и тот же вопрос несколько раз, они могут сказать «Прочитай руководство по ебли» (RTFM), но для этого им нужно иметь «Руководство по ебли» (FM).


Что происходит, когда технические руководители пишут документацию?


В случае, когда технические руководители или старшие разработчики решают написать документацию, проблема поддержания документации == в актуальном состоянии == все еще возникает.


Им нужно ответить на вопрос == «что если код изменится?» == потому что без четкого ответа разработчики думают == «зачем мне писать документацию, если завтра она может устареть?» ==.


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


Проблема:


  1. Технические руководители должны иметь некоторую документацию.

  1. Технические руководители не могут тратить много времени на написание документации.

  1. Разработчики могут писать документацию распределенным способом, но они должны быть уверены, что их время не будет потрачено впустую.

Текущие решения для технических руководителей:


  1. Вообще не пишите документацию, ежедневно отвечайте на вопросы. Это решение будет работать до некоторой степени! Особенно в небольших компаниях, где у вас не так много заинтересованных сторон.

  1. Автоматическое создание документации из кода. Подходит только для документации, подобной API, но не подходит для документации по бизнесу/продукту.

Решение: наличие системы, связывающей документацию с кодом


Это для меня кажется жизнеспособным решением.


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


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


Вывод


Никто не будет обвинять вас в том, что у вас нет документации или она ограничена.


То же самое было распространено 20 лет назад с тестами. Никто не обвинял вас в том, что у вас нет тестов или они ограничены — потому что каждая команда написала хороший код, в котором не было ошибок, поэтому его не нужно было тестировать :)


Точно так же сегодня каждая команда пишет самодокументирующийся код, который каждый может прочитать, чтобы понять, что внутри… ;)


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




Оригинал

Recent Post

Categories

PREVIOUS ARTICLE
NEXT ARTICLE