Миф о документации, продолжение
И самое интересное - стоит сказать про "документацию" правду, которую в глубине души и так все знают, - и это обычно провоцирует бурление говн, и поток самых невероятных высказываний.
Давайте посмотрим, почему же люди пишут документы тогда, когда они их действительно пишут, а не рассуждают о том, как бы хорошо было, если бы они были, и как плохо, ( Read more... )
Давайте посмотрим, почему же люди пишут документы тогда, когда они их действительно пишут, а не рассуждают о том, как бы хорошо было, если бы они были, и как плохо, ( Read more... )
Comments 280
Reply
Из рабочего - можно "презентации" добавить. Тоже особый тип документа - иллюстрация к докладу. Его сговнякать элементарно, впрочем. Если знаешь, что хочешь сказать. А если не знаешь - лучше вместо слайдов рисовать картинки :).
Reply
есть тонкость.. нужно знать не что хочешь сказать, а что хотят услышать.. :)
Reply
Reply
Чтобы через год те, кому я дам эту ссылку, не шарились по всемиу ЖЖ по полдня ;)
Reply
> Ну, наверное - «если написать один раз, то это будет лучше, чем объяснять ее двадцать пять раз». Это распространенное заблуждение тех, кто никогда не пробовал писать учебников. И любимая отговорка тех, кто не умеет толково объяснять.
Неверный логический переход. Во-первых постулируется что писать буду потому не умеют объяснять. Это может быть не так, часто пишут именно что бы не объяснять 1000 раз ("какие параметры у скрипта и где его файлы.")
Так же кроме учебников есть "методички", "распечатки", а не только "учебники", и прочие мелочи, которые дают обзор, не ставя целью полный охват.
> за неуказание в них номера задач в трекере и фамилии проверяющего - убивать на месте.
Если довести до такого маразма, это будет мешать работать, когда надо ради исправления опечатки в коменте (и тд. по непрерывному росту важности, опечатка в переменной, неправильный отступ, не очень понятное место кода, ...) работать с Jira/звать ревьювить.
Reply
Нет такого утверждения в моем тексте.
> Это может быть не так, часто пишут именно что бы не объяснять 1000 раз ("какие параметры у скрипта и где его файлы.")
Это справочная информация, а не учебная.
> Если довести до такого маразма, это будет мешать работать, когда надо ради исправления опечатки в коменте (и тд. по непрерывному росту важности, опечатка в переменной, неправильный отступ, не очень понятное место кода, ...) работать с Jira/звать ревьювить.
Регулярно совать руки в код без веской на то причины, просто "переписывая непонятный код", рискуя при этом вызвать ошибку, при этом топая ножкой, и настаивая на праве коммита этой не имеющей ценности для пользователя самодеятельности в транк без ревью - это не есть "работа". Это источник ошибок, и саботаж.
А если это делается в рамках и в процессе работы по существующей задаче - то достаточно в комментарии к коммиту это упомянуть.
Reply
Reply
>> Нет такого утверждения в моем тексте.
> Альтернатива в тексте не рассматривается, только красочно расписана как неправильно когда пишут те, кто не умеют объяснять.
Опять таки, нет ничего подобного в моем тексте.
Люди, не умеющие (и не желающие) читать, что написано, лишаются права комментировать в моем журнале.
http://linorg.ru/how-to-read.html
Ибо объяснять им что-либо бесполезно. Всего доброго.
Reply
А как технически осуществляется доставка кода проверяющему, его же может быть много? Или просто позвать за свой комп?
Reply
Есть и другие варианты с использованием спецсредств, например, Atlassian Crucible.
А можно показать изменения с экрана своего компьютера, и заодно объяснить их - это самое простое.
Reply
Reply
Накладных расходов почти нет - ревью делается тычками в файлы коммита в описании задачи в трекере. Ссылки ведут на diff в вебморде VCS. Это - результат интеграции трекера и VCS. И это действительно удобно. Людям нравится.
Crucible, и прочие тулы для code review, позволяет реализовать более гибкие схемы.
Reply
>понятным образом излагать свою мысль на родном языке. Категорически. Эта
>работа им противопоказана.
Я смотрю у Вас толпа программистов стоит за воротами и все молятся чтобы именно их приняли на работу? Лично я согласен иметь помощника, можно 2 которого буду понимать только я, при условии что они будут хорошими экспертами. Базовыми навыками телепатии владею )
Reply
Выбор из нескольких кандидатов на позицию есть всегда и у всех. Естественно, каждый из кандидатов хочет, чтобы взяли именно его - обратное было бы глупо. А молятся они об этом или нет - мне искренне по барабану. У нас не монастырь.
> Лично я согласен иметь помощника, можно 2 которого буду понимать только я, при условии что они будут хорошими экспертами. Базовыми навыками телепатии владею )
Буду иметь в виду эти ценные для меня сведения . :)
Reply
Reply
Это сказал Дейкстра.
Он, как и я, считает это не "заскоком", а необходимым качеством хорошего программиста. Таки да, его, хорошего, так проблематично найти.
Однако, я сказал не совсем то же самое, что Дейкстра. Я сказал, что людей, которые не могут связать на родном языке двух слов, нельзя брать на работу. Ибо он и на более формальном языке программирования двух слов связать не сможет. Тут речь вовсе не о mastery, а о прямой ее противоположности.
А что вы считаете - это ваше дело, я свою точку зрения никому не навязываю.
Reply
Leave a comment