?

Log in

No account? Create an account
November 2016   01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
cartoon

Миф о документации, продолжение

Posted on 2011.06.18 at 23:06
Tags: , ,
И самое интересное - стоит сказать про "документацию" правду, которую в глубине души и так все знают, - и это обычно провоцирует бурление говн, и поток самых невероятных высказываний.

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

MoreCollapse )

Comments:


Page 2 of 2
<<[1] [2] >>
melkus
melkus at 2011-06-19 14:06 (UTC) (Link)
>И самое интересное - стоит сказать про "документацию" правду, которую в
>глубине души и так все знают, - и это обычно провоцирует бурление говн,
>и поток самых невероятных высказываний.

Ну этот пост не далеко ушел по провокационности от первого, всё таки многое спорно или возможно недостаточно детализировано.
Gaperton
gaperton at 2011-06-19 14:30 (UTC) (Link)
Странно, а я в нем ничего провокационного не вижу. Спорное - ну попробуйте поспорить. Если не будете переводить обсуждение на личности - то это вполне безопасно. А если будете - то это очень быстро закончится ;)
(Deleted comment)
Gaperton
gaperton at 2011-06-19 14:31 (UTC) (Link)
Поясните, что в точности вы имеете в виду под обоими видами.
(Deleted comment)
(Deleted comment)
(Deleted comment)
blueher at 2011-06-19 18:13 (UTC) (Link)
Я бы добавил ещё один вид документации - "time capsule" или "письмо себе N+10-летнему" - обычно пишется не при написании кода, а при отладке, когда программист понимает что забыл как работает этот код и сам для себя (для следующей отладки) это описывает. Это не договор (пишется в основном для себя и по факту сделанного) не справочник (не поддерживается в актуальном состоянии) и не учебник (пишется для себя или человека на себя похожего). Это как правило довольно внятная документация (пишется же для себя) без "воды", охватывает только самую суть.
Gaperton
gaperton at 2011-06-19 18:17 (UTC) (Link)
Я такое обычно в комментариях к коду писал. Так оно вернее дойдет. И когда понадобится - будет находится в самом годном для этого месте. А то обидно будет, если послание в будущее отправишь, но забудешь, где почтовый ящик, и в какой момент его надо открыть, верно?

А программный код - это особый вид технической документации. Это исполняемая спецификация.
igorilla
igorilla at 2011-06-20 00:12 (UTC) (Link)
- Донести до программистов простую мысль, что программа пишется в первую очередь для человека, и только во-вторую – для компьютера. Из этого много чего следует, например, то, что у идентификаторов должны быть осмысленные имена, и код должен быть в первую очередь понятным.

32 года тому назад эти идеи было откровением, что, ничего не изменилось на Руси ?
Gaperton
gaperton at 2011-06-20 21:35 (UTC) (Link)
Комменты почитайте. Они сами за себя говорят.
Ласка
wesel at 2011-06-20 08:33 (UTC) (Link)
Комментариев не читала, прошу прощения, если этот вопрос уже задавали. Как реализуется пункт с review при использовании Subversion? Не вижу навскидку вменяемого способа прочитать чужой код до того, как он попадет в репозиторий.
Ласка
wesel at 2011-06-20 09:20 (UTC) (Link)
Прочитала комментарии, вопрос снялся (:
Alexander Belchenko
bialix at 2011-06-20 13:31 (UTC) (Link)
Как насчет описания протоколов общения между отдельными узлами системы? Мы это всегда в носим в вики потому что пользуемся ну почти каждый день, т.е. это типа "договора", но по мере развития системы в протоколы вносятся добавления. В какую категорию тогда относятся наши протоколы? Я думаю, что между "договорами" и "справочниками". На code review проверяется соответствие нового кода протоколу.
Gaperton
gaperton at 2011-06-20 21:32 (UTC) (Link)
Отличный вопрос. Если обобщить- это "внешний интерфейс системы", протокол с контрактом.

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

И это действительно значимый пример. Вы нашли "дырку" в рассуждении. Спасибо.
pingback_bot
pingback_bot at 2011-06-22 09:29 (UTC) (Link)

Миф о документации, продолжение

User dr_cha0s referenced to your post from Миф о документации, продолжение saying: [...] по полочкам. Автору отдельное спасибо. Originally posted by at Миф о документации, продолжение [...]
pingback_bot
pingback_bot at 2011-06-22 10:28 (UTC) (Link)

Проектная документация и Scrum

User goldtester referenced to your post from Проектная документация и Scrum saying: [...] ;и "Миф о документации. Продолжение" [...]
eao197.blogspot.com at 2011-06-23 06:52 (UTC) (Link)
Есть еще две причины, по которым люди пишут "учебники"

1. Графомания. Т.е. "писатель пишет не тогда, когда может писать, а тогда, когда не может не писать". Вне зависимости от признания. Захотелось, написал. Явление, конечно, редкое. Однако, имеет место быть. В частности, очень часто можно видеть в технических блогах. Когда человек разобрался с какой-то проблемкой и чиркнул в свой блог пару-тройку заметок о том, что, как и почему заработало.

2. Продвижение собственной разработки. Написал кто-то библиотеку. Для того, чтобы ей захотело воспользоваться чуть больше чем несколько коллег с общего проекта, нужно сделать какое-то описание.
zigel
zigel at 2011-06-23 07:11 (UTC) (Link)
В нашей конторе пришли к этому собственной кровью:
Jira + Fisheye + Subversion.
Проекту, сорцам то есть, уже больше десяти лет, работает третье-четвертое "поколение" программистов. Все сначала воют по поводу отсутствующей или неактуальной доки.
А теперь стату кво:
хук на коммите, привязывающий к номеру задачи или названию модуля (нежелательно, но разрешено), опциональные код-ревью с crucible,
вики, куда добровольно пишутся факи и примеры.
ну так, типа, все и решается.
Pavel Egorov
xoposhiy at 2011-06-23 09:28 (UTC) (Link)
Вот ещё одна причина в копилку:
Написать устройство сложной штуки, чтобы его почитали другие и выявили проблемы, например, ещё до написания кода. Или, например, потому что не получается организовать код также удобно для чтения как текст.
chmelvv at 2011-06-25 17:48 (UTC) (Link)
Недобрый день!
Впервые зашел на ваш блог.
По сути топиков видно, что вы человек дела и воды не льете. Это классно!
Но меня удивило огромное количество мата. Это типа кул?
К чему оно? Кроме раздражения ничего не вызывает.
Чесно говоря, просто физически хочется пойти помыться ...
Gaperton
gaperton at 2011-06-26 15:22 (UTC) (Link)
В следующий раз забаню за оффтоп.
valerkar at 2011-08-25 04:56 (UTC) (Link)
подпишусь под каждым словом. Единственно что - договор - достаточно в широком смысле может трактоваться - у нас обычно необходимость в документации возникала только при общении с заказчиком, с двумя основными целями - зафиксировать scope проекта, согласовать интерфейсы для интеграции. В разработке,и суппорте особенно - issue tracker (TFS) с возможность ассоциировать чекины с задачами - вещь бесценная для суппортера. И что-то wiki - продобное для храниния урлов, логинов, спецификаций. А с "учебниками" у нас было как-то не очень.
Ласка
wesel at 2012-02-25 15:47 (UTC) (Link)
Прошу прощения за комментарий в довольно старом посте, и тем не менее, хочу задать один вопрос.

Как Вы решаете проблему масштабируемости процесса передачи знаний о работе программы? Предположим, есть архитектор, который знает, как все работает. Есть некоторое количество внедрений и клиентов, которые генерируют запросы - не нравится то, не нравится это, хотим вот такую фичу, не понимаем, как работает вот это, не знаем, как поступать в такой ситуации. Есть некоторое количество внедренцев, которые с клиентами общаются. Архитектор\программисты будут консультировать каждого из них? По мере появления вопросов? А когда они будут кодить, в рабочей неделе всего 40 часов? (:
Gaperton
gaperton at 2012-02-28 12:37 (UTC) (Link)
При большом количестве обращений внедренцев, которое наблюдается в моменте - внедренцы собираются вместе, и для них проводится организованное обучение - набор лекций/семинаров. Это сразу снижает количество обращений.

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

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

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

И все. В зависимости от характера работы внедренцев, может оказаться целесообразным вести для них документацию по типовым случаям, или "справочники". А может и нет - описываемая мной схема во многих случаях делает возможным ненапряжную передачу знаний и без документов.
Previous Entry  Next Entry