Комментарии 27
Из дел по дому моё любимое — мыть посуду. Почему?
Я полюбил процесс мытья посуды, будучи еще студентом, когда купил посудомойку. Это, кстати, была вторая большая покупка на вырученные с курсовых проектов однокурсников средства, сразу после покупки ноутбука.
Я вот в детстве ненавидел мыть посуду, а сейчас это стал какой-то медитативный процесс - даже расслабляет..
медитативный процесс - даже расслабляет
У меня такая же фигня - с глажкой "плоского" белья (полотенца, простыни/пододеяльники и пр.). А если на фон еще регги включить... :)
Причем иногда ответы на нерешаемые вопросы сами приходят в голову в процессе наведения порядка в посуде и кастрюлях.
Шайтан терапия.
Присоединюсь! Жена как-то раз дала попробовать поставить посуду, и я подсел.
Под мытьё посуды ещё хорошо заходят подкасты.
Ага. Аудиокнига и спящие жена и дети...
Я так диссертацию написал - пока мыл посуду, обдумывал текст, а потом шёл записывать)
И да, сейчас для меня это тоже медитативное, успокаивающее занятие.
пойду ка я тоже посуду помою.
Документация - это совсем не то, что люди обычно подразумевают. Не что-то такое, что новые люди приходят и начинают читать. Потому что а) не начинают (даже если что-то есть), и б) ее нет (потому и нет, что нет аудитории, невостребовано).
Здоровая документация (а не для галочки, и не для того, чтобы с умным видом задавать вопрос «а документация у вас есть? ах нет? ну тогда вы полное г-но, а я д’Артаньян») бывает только одного типа, и образуется она всегда одинаково. А именно:
Сначала ничего нет.
Потом приходит человек, который ХОЧЕТ что-то делать (желание тут - ключевое; симбурде не прокатит) и спрашивает. Вы отвечаете.
Он снова приходит. И спрашивает. И спрашивает. Вы снова отвечаете.
Потом приходят еще 3-4 человека и спрашивают ровно то же самое.
И вот в этот момент рождается ДОКУМЕНТАЦИЯ. Как ваша реакция на однотипные вопросы.
Теперь, когда приходит человек с тем же вопросом, вместо того чтобы ему новое сообщение строчить, вы даете ссылку на уже готовый ответ в документации.
Люди продолжают приходить и задавать новые вопросы, так что документация обрастает все новыми деталями и полируется, эволюционно.
То есть для рождения документации (а не «документации») должны встретится две необходимости: реальное желание внешних людей что-то делать и продвигаться вперед, и лень автора документации отвечать на одинаковые вопросы. Уберите хотя бы один компонент - и будет «документация», а не Документация.
Можно также перечитывать раз в несколько месяцев написанное самим собой и оценивать, что уже стёрлось из памяти и что надо написать явно.
Но в целом я согласен с тем, что без реакции на обратную связь документация обычно крайне слаба.
Автор документа и читатель документа — это два разных человека. С разной квалификацией, опытом, образованием, а возможно и другим родным языком, и т.п. и т.д. И то что автору очевидно, читателю может быть сложным.
Есть общие принципы требования к квалификации читателей, которые позволяют разрешить эту проблему.
Только обычно этим не хотят заниматься, это ж учиться надо.
Вовсе не обязательно по этой причине. Понять, какова квалификация читателя — это работа. Даже если умеешь. Учиться — кстати тоже. А значит это время и деньги. А их никогда не бывает слишком много.
Иногда и читателя как такового еще нет (мы лишь знаем, что он будет — но живьем его никогда не видели). А мне говорят — у вас будут вот такие пользователи, для них нужно написать документацию. А на вопрос, какова их начальная квалификация, все только пожимают плечами.
Я могу конечно написать, что наш читатель должен знать вещи а, б и в, но это совершенно не решает проблему — потому что из того факта, что я это потребовал, совершенно не следует, что читателя кто-то этим вещам научит (и не дает ответа на вопрос, кто именно научит, и кто за это заплатит). Ну так, в качестве условного примера — я исхожу из того, что читатель владеет SQL. При этом у меня нет ни времени, ни ресурсов, чтобы его научить. Решает ли это требование проблему низкой квалификации читателей, которые не владеют SQL? Нисколько. В лучшем случае я таким требованием сниму с себя ответственность. Но разве это решение?
Вообще-то обсуждение началось в контексте инструкций для коллег-программистов, в крайнем случае QA. А у них обеспечить базовые требования к квалификации сильно проще.
> Решает ли это требование проблему низкой квалификации читателей, которые не владеют SQL? Нисколько. В лучшем случае я таким требованием сниму с себя ответственность. Но разве это решение?
Да, решение. Должен коллега-программист знать SQL достаточно, чтобы понять, что происходит (или хотя бы смотреть, что это?) — должен, иначе его поспешили взять сюда на работу. Ну или пусть шустро осваивает.
Усиление же вашей позиции приводит к тому, что вообще ничего от кого нельзя хотеть и предполагать знаний. А это не просто перебор — это развал цивилизации.
Не, ну у меня ни те ни другие, у меня скорее речь шла о поддержке — которая должна знать специфику нашего продукта, о котором не рассказывают в книжках. То есть знание SQL — это лишь часть вопроса.
>Ну или пусть шустро осваивает.
Ну он так и делает. Я к тому, что очень редко удается найти кандидата на вакансию, который идеально подходит. А тут это вообще не кандидаты, это бизнес нам говорит: вот вам новые (необученные) люди, они вам помогут сделать вот эту работу. И это просто сотрудники других отделов, я не могу попросить их уволить и заменить новыми, это бизнес, который платит мне деньги, в конце концов.
>Усиление же вашей позиции приводит
Ну как бы довести до абсурда можно что угодно. По сути же я говорю о том, что потребовать каких-то знаний конечно можно, но в реальности они скорее всего появятся только после (до)обучения, то есть несколько позже. Само требование их автоматически ниоткуда не возьмет. А обучение это ресурсы, время, деньги, люди и так далее.
Или другие 3-4 человека, с другими задачами. И спрашивают совсем другое. И получается документация другого вида.
Отдельное спасибо за «daily» вместо «дэйли» ;-)
Как часто вам приходилось слышать фразу «код — это лучшая документация»
Как трудно переубедить в обратном коллег и руководство пока только начинаешь работать в компании. И только по прошествии полугода, при карьерном росте или заматерелости в проекте начинает удаваться что проталкивать. Ну хотя бы doc string в начале функции. А на уровне лида приходится доказывать необходимость документирования уже разговаривая с CTO.
Поправка: хороший код -- это документация. Плохой код -- это расписка в профнепригодности, что тоже можно считать документом.
Поправка: хороший код -- это документация.
Хороший и простой код может сам себя объяснять. А бывает код хороший и в то же время сложный, когда возникают вопросы "Почему?" и "Зачем?". Если документации нет, спросить у кого-то невозможно, то придётся самому искать ответы. А это время.
git blame. Смотрим для каждой строчки сложного кода историю изменений. Ответы "почему" и " зачем" даем в сообщении к коммитам.
Даже в случае жесткого легаси кода, если мы действительно стремимся ситуацию улучшить, для каждого изменения четко описываем, что мы поняли в том комке грязи, с которого мы начинали изменение, какова была цель и чего в этом коммите мы НЕ достигли. Каждая ветка строится по принципу "инструкции по приготовлению" в виде четких простых шагов, как мы из комка грязи получаем что-то оформленное. Время, затраченное на переосмысления собственных изменений (git rebase -i) окупается с лихвой улучшением пропорции cohesion/coupling.
Лучшая документация -- это история коммитов. Вернее, так должно быть. По факту большинство игнорирует этот мощный инструмент передачи знаний. А зачастую убогая история изменений свидетельствует о том, что и передавать-то нечего...
Нет.
Потому что история коммитов — это диахроническое состояние, о том, как развивалось что-то в процессе. А документация конкретной версии — это синхроническое, о конкретном состоянии.
Разница хотя бы в том, что, например, 200 опций конфигурации и их особенности в текущий момент — документация описывает индексируемым списком, по иерархии и/или по алфавиту, а история коммитов не просто будет содержать их в произвольном порядке, но и с кучей ненужного сейчас типа «опция --moo-list была --moo до 2.2, потом до 2.5 содержала 2 параметра, а теперь один — имя ключа для выбора», и с тяжёлым поиском нужного, когда что-то меняется на 5-м уровне индиректности.
Всё-таки с синхронным профилем на порядки легче:)
История гораздо богаче отдельного среза. Бережное отношение к истории дает более глубокий источник информации. Если очень хочется описания всех 200 опций, то делаем линку из отдельного коммита на конкретную версию доки для тех опций, которые актуальны в данный момент. Имеем не одну доку последней версии, а историю этой доки, что намного полезнее.
PS Я не отрицаю полезность любой другой документации.
Я и не говорил ничего против этого:)
> Если очень хочется описания всех 200 опций, то делаем линку из отдельного коммита на конкретную версию доки для тех опций, которые актуальны в данный момент. Имеем не одну доку последней версии, а историю этой доки, что намного полезнее.
Или не линк, а изменение где-нибудь в docs/ с этим же коммитом. Это уже по обстановке. Но главное, что именно удобство синхронического взгляда (в любой момент, в настоящем или прошлом) избавляет от необходимости перерывать всю историю.
> PS Я не отрицаю полезность любой другой документации.
А я не понял, чем эта «любая другая» отличается…
Поздравляю с новой работой