Миф о документации

[gaperton]

Программист, заступая на новую работу, каждый раз искренне изумляется и негодует, что "система не документирована". Это негодование - по соей силе бледное подобие негодования второго рода, которое тот же программист испытывает, если ему предложить описать простым человеческим языком, что он недавно наколбасил. И не забывать регулярно обновлять

Comments

No title

[pingback_bot]

User squadette referenced to your post from No title saying: [...] ь каждый раз, когда он вносит в колбасево изменения. http://gaperton.livejournal.com/60277.html [...]

[vozbu]

Эт что за мифический программист такой? По-моему наоборот должно быть - приходишь на новую работу с мыслью "и здесь наверное никакой документации, кроме кода", а тут на тебе - все описано и регулярно обновляется. Вот это сюрприз!

[gaperton]

Ага. Еще если б мозг напрягать не пришлось при ее чтении, и все без усилий понятно было б - это вообще сказка была бы.

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

[raccoon]

Ага. А уж аналитик, который пишет требования - это по-любому плохой, негодный аналитик. Потому что один же черт непонятно ни хрена.

[yakov_sirotkin]

Практически на каждой новой работе мне говорят, что у нас есть wiki или sharepoint в котором всё записано. И там ни черта нет не устаревшего! Сам начинаешь потихоньку какие-то документы выкладывать (если есть wiki), пытаешься привить культуру.

[malica_dee]

Документирование каждой функции и каждого класса, кроме того самого случая публичного API, действительно нахрен никому не нужно, но я не могу сказать, что документация в принципе не нужна. На проекте нужны доки, которые описывают архитектуру, протоколы, формат конфигов и т. п. И эти доки (с тяжкими вздохами и регулярными упражнениями в употреблении обсценной лексики) таки пишутся большинством программистов.

документацию пишут козлы для козлов, а победители пишу

[dmarsentev]

Из личного опыта

Re: документацию пишут козлы для козлов, а победители пи

[aamonster]

Re: документацию пишут козлы для козлов, а победители пи

[aamonster]

Ну и насчёт здоровых отношений: могут быть нормальные отношения между сотрудниками, никто никого не пытается подсидеть... Но документация всё равно не пишется, потому что "вот именно сейчас - некогда".

Re: документацию пишут козлы для козлов, а победители пи

[gaperton]

Такие вещи оформляйте, пожалуйста, постом в собственном журнале, а в комментатиях здесь давайте на него ссылку.

Я прошу вас перенести все эти комментарии в свой журнал.

не уместилось

[dmarsentev]

Ну и в-четвёртых:
когда программерская документация формируется естественным образом?
Например, когда выцепляется кусок системы и отдаётся на аутсорс.
Незнакомым людям.
В чужие руки.
И они нам будут писать функции, которые мы будем вызывать?
Ой, мамочки. Срочно писать спеки!
Вот тогда программист посылает начальников подальше,
потому что начальники говорят "да это всё фигня,
да ты спихни как-нибудь, да документация - это вообще не работа".
Такого начальника программист шлёт подальше
и пишет - не только тесты, но и документацию -
весьма скрупулёзно и продуманно.

Т.е. всякие приёмо-сдаточные процедуры - они
естественным образом генерируют качественную документацию.

Re: не уместилось

[raccoon]

Да, мы с моим бывшим PMом (Иван Поваляев, до недавнего времени - Sitronics Telecom Solutions) пытались пропатчить мозг этим подходом добрым людям на Software People. Добрые люди жевали попкорн, дивились на Дарта Вейдера, гулявшего в коридоре, но нам не внимали.
Есть старый метод написания требований к системе: создать прототип пользовательской документации. А потом дополнить приемо-сдаточными процедурами.
По-моему, как раз agile-подход на сходном принципе построен.