На мой взгляд любой исполнитель должен быть не “специалистом по левой ноздре”, а хотя бы в общих чертах представлять весь процесс, в котором он участвует. Чем ближе процесс к нему, тем лучше он его должен представлять. Т.е. конкретный специалист он не потому, что знает только что-то одно, а потому что именно свою область знает лучше всех. Соответственно, программист должен знать, как составлять требования, как управлять проектом, как приоритезировать задачи и управлять бэклогом, как развертывать с нуля приложение на всех средах, как задокументировать изменения и т.п. При этом он может не вникать в какие-то мелкие детали, т.е. работа остальных специалистов для него серый ящик (ближе к белому), но ни в коем случае не черный.

Соответственно, в моем представлении хороший аналитик, как и любой другой специалист, должен понимать, в чем заключается работа программиста и как в общих чертах работает сервис. Более того, классический аналитик — это связующее звено между белой горячкой заказчика и рефакторным мракобесием/архитектурной упоротостью разработчика, поэтому он должен хорошо понимать как одного, так и другого.

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

  1. Разработчик сам пишет документацию в общих словах по ключевым алгоритмам и в рамках выполнения тикета обновляет рабочую документацию в Wiki. Рабочкой пользуются все внутри команды, там написано разрабами для разрабов, но и другим членам команды понятно.
  2. Когда надо сдавать официальные доки, техписатель из рабочки создает документацию по всем ГОСТам, написанную для заказчика и его специалистов. Если что-то непонятно — читает код. Если что-то совсем не понятно — спрашивает разрабов.

Понятно, что не на каждый проект такое натянешь, но идея того, что техписатель читает код, на мой взгляд, вполне адекватна.

По поводу степени подробности документирования: тут важна золотая середина. Мало подробностей или ноль — документация бесполезна и никому не нужна (однако немного документации все-таки лучше, чем ноль). Много подробностей — много времени, чтобы ее постоянно актуализировать (или она устаревает), и ее тяжело хорошо структурировать. Мы исходили обычно из потребности. Т.е. есть какая-то база, дока на которую должна быть обязательна: краткое описание функции сервиса, перечень его контрактов, взаимодействие со внешними системами, крупными мазками схема с архитектурой (в мире ведь не только микросервисы с рестами бывают), конфигурация (если там что-то не очевидно). Кроме базы есть еще нюансы, нетривиальности и т.п., которые нужно описывать с бизнесовой или функциональной точки зрения, чтобы не только понимать, почему в коде наверчена нетривиальная шляпа, но и понять, когда ее можно убрать. И бывают сложные реализации, когда по какой-то причине не получилось сделать просто — это тоже описываем. На всякую мелочевку по реализации ответят код и юнит-тесты. А все остальное скорее всего очевидно и вряд ли кому-то нужно.

Я думаю, что документация должна быть частью процесса, но не единой сущностью с кодом. Все эти javadoc, doxygen и т.п. хороши для библиотек, когда тебе по-быренькому надо посмотреть что-нибудь и лень читать нормальную документацию. В обычном коде комментарии нужны только для неочевидной шляпы (и это реально редкий кейс). Документация именно кода скорее вредна — это будет либо капитан очевидность, либо суррогат нормальной документации. Если код нормально написан, то он самоописательный (самодокументирующийся).