Gaperton разразился текстами про документацию, к сожалению текст не везде цензурный, но по делу лучше читать сразу продолжение http://gaperton.livejournal.com/60632.html исходный пост тут http://gaperton.livejournal.com/60277.html Кто не сочтет возможным для себя читать не гладко выраженные мысли, краткое резюме: в документации есть две стороны писатель и читатель (тема читателя до конца не раскрыта ) есть три типа программистской документации: 1) "Договор". - для это ТЗ или задачи в трекере 2) "Справочник". - то что с трудом пытаемся писать в wiki и код, но для кода нужен ключ доступа новым читателям. 3) Обучающий материал. - то что нужно создать, но стоит очень дорого
Для ключей к справочникам нужны: 1. номера ревизий закрывающие задачи (чего не всегда делается) 2. коменты по задачам, удаляя срач мы удаляем часто единственные зацепки которые позволят понять устройство системы Отсебятина к тексту, дополнительно нужны: 3. описание архитектуры, как ее состыковать с кодом хз 4. документы по прохождению развилок, хз как писать 5. модель для проверки консистентности постановок, хз как ее реализовать все выше написанное не отрицает того, что документация важна и нужна
Комментариев нет:
Отправить комментарий