Підписуйтеся на Telegram-канал «DOU #tech», щоб не пропустити нові технічні статті
Все чаще замечаю что люди не умеют читать документацию. Они скорее будут искать на стек оверфлоу чем читать доку, либо всех вокруг задрачивать — при чем те кто вокруг, тоже доку нифиги не читает.
Да что там доку, часто задание в Джира не читают хоть там четко написано что должно быть сделано по пунктам.
Вот все таки любопытно, почему это так сложно?
Ну ты и тему поднял :)
Я в качестве затравки приведу такой факт. В Unix есть такая софтина под названием sendmail. Кто с ней сталкивался — меня, считай, уже поймёт. У неё крайне нетривиальная и весьма непривычная система конфигурации, происходящая из ряда специфических академических традиций. И вот во время работы в LuckyNet мне надо было её освоить на приличном уровне. Была печатная книжка, хоть и чуть старая, но очень близкое к ней содержимое можно было получить на любой из ближайших BSD систем в /usr/share/doc/smm/08.sendmailop — то есть документация была под рукой аж в двух видах, надо только прочитать. И вот читаю я это и тупо нихрена не понимаю. Один цикл, второй, третий... всё равно без толку.
И тут я ловлю грипп. И вот ситуация: лежу я такой с температурой 39, спать не могу, не штырит, но состояние именно такое, что нечего делать кроме как валяться; делать ничего не хочется, но и скучать — тем более. Взял книгу по sendmail и тупо последовательно читал. И что... где-то на
Ещё пара похожих ситуаций была с прослушиванием Башлачёва (кто знает — у него большинство песен пронзительны настолько, что серьёзно слушать их это мини-катарсис), некоторыми книгами. «Моби Дик» в пионерском лагере в пост-чернобыльском летнем изгнании — делать нечего, а у неё... 5/6 неинтересны, но без них последнюю часть не понять; 1/6 — приключения, события, но что и зачем — без первых 5/6 не понятно, кто, зачем и почему; я раз 5 её начинал, бросал и возвращался. Прошёл в итоге только потому, что понял, что иначе не получится. Книга очень понравилась :)
Кто-то может счесть это чуть ли не рекламой всякой химии для вхождения в состояние спокойного освоения. Я никак такое не поддерживаю; наоборот, считаю, что надо воспитывать в себе такое умение просто как естественный метод. Но факт — то, что огромное количество людей слишком нетерпеливы, чтобы спокойно читать и понимать, сосредотачиваться на одной теме и думать над ней продолжительное время. Вообще это считается проблемой тех поколений, что сейчас 20 (в крайнем случае, 25) лет и младше (слова типа «клиповое мышление» и т.п.), но очень заметно было и раньше. Если такой человек заинтересован разобраться, он потратит больше времени (из-за переключений), но разберётся. Если нет стимула, необходимости — он тупо забросит тему, выкрутившись простейшим образом (как то же копирование с SO) и ничего не поняв.
Второй, встречный вопрос — это качество и стиль самой документации. Здесь типовые проблемы:
1. Неупоминание того, что очевидно для пишущего, но никак не будет таким для типичного читающего. Например, даётся просто список функций в духе:
create_foo() - создать красную зюку
create_bar() - создать синюю зюку
zuka_run() - заставить зюку бежать
Что такое зюка — тебе не расскажут. Для автора очевидно — он рисует зюки уже 10 лет. Ты же пришёл сюда за средствами управления кузявостью бутявок. Что зюка это правосторонняя бутявка, или правосторонняя чуняхва — ты не знаешь и узнать это не так просто (поиск в гугле будет засорён так, что не найдёшь).
Точно так же ты не будешь понимать, почему красная зюка зовётся foo, а синяя зюка — bar.
2. При нетерпении читающего к неочевидности обычно примешивается собственная интерпретация на основании того, что очевидно для читателя. Принцип для соответствия читателю называется POLA. Пример из личного опыта:
Есть конфигурация некоторых сущностей, которую надо править руками на
Я: — Ты что сделал? Оно же пишет не то, ещё и ломает соседей.
Коллега: — Ты инструкцию читал? Делай ровно по ней. Вот тут и тут: что писать, куда вводить.
Я: — Ты же сказал, что всё реализовал? Оказывается, не всё, ещё и не так, как нам нужно.
Коллега: — Читай инструкцию! Там всё написано!
Ещё несколько кругов, в которых повторяется одно и то же — он говорит, что всё написано, я — что такая недоделка нафиг не нужна. Коллега всерьёз обижается — он, мол, сверх обязанностей сделал хорошую вещь, а всякие неблагодарные тут...[ольгабогомолец] Я тоже обижаюсь — за хорошо спрятанную в инструкции объёмную свинью и за то, что вместо адекватной реакции на багрепорт (я не хотел благодарности, но хотя бы молчаливого исправления) — «сам виноват, что не прочёл». Ну да, в чём-то я был виноват. Надо было включить режим юриста и вчитываться в каждую букву, но мне тогда это было непривычно, да и сейчас — можно так делать, тратя на это заметные усилия, но как хорошо, когда это не нужно.
TL;DR: когда пишешь для другого, надо иметь хотя бы элементарное понимание, как твой выхлоп будут читать и понимать.
Обычно при нормально настроенной обратной связи в этом случае появляется ряд замечаний с явным подчёркиванием каких-то особенностей, извинений за legacy (как у конкретного продукта, так и общеотраслевое, типа «не мы придумали этот термин», и так далее). Но если люди не хотят обратной связи, то результат так и останется кривым.
3. Сосредоточение на каком-то одном стиле документации, вместо того, чтобы разобрать лучшие практики и сделать объединение нескольких подходов.
В этом плане мне всегда нравился подход Microsoft — независимо от качества самого софта. В документации у них каждая глава имеет три секции:
— overview — что это такое, зачем нужно, ограничения
— using — как пользоваться, начиная от самых типовых сценариев и продолжая до хитрых особых случаев
— reference — справочник по алфавиту ко всем сущностям
Начинаешь с overview и таки понимаешь, зачем оно такое и вообще нужно ли тебе (хотя можно и промазать — но тогда уже только гугление). Смотришь типовые сценарии, уже есть в голове скелет для заполнения. Начинаешь набивать мясом и прочими причандалами, получаешь что-то близкое к нужному, шлифуешь детали. Всё просто и прямолинейно.
В Unix мире аналогичный подход в одном флаконе представлен обычно у тех продуктов, у которых есть texinfo — документация — её пишут по такому же принципу. А вот до появления info было сильно хуже. Типичный анекдот тех времён:
Крошка сын к отцу-сисадмину пришёл, и спросила кроха:
— Папа, а почему солнце ходит по небу!
— RTFM!
— man что? — привычно спросила кроха.
Так вот, это самое «man что?» было стандартной фразой по несколько раз на дню потому, что инструкцию по конкретной функции или программе можно было ещё понять, но узнать, что такое вообще существует и имеет отношение к данной теме — только добывать опросом по коллегам. Ну или по книгам, которые тогда были крайне редки (какого-нибудь Стивенса мы добывали жуткими сложными путями). Иногда в манах были кросс-ссылки, но обычно неполные и рассчитанные на спеца, который просто забыл в запарке, куда смотреть, но не на новичка. Ну и сами маны были часто написаны так, что нифига не понятно, даже если прочтёшь. Уже позже появилась манера добавлять хотя бы простейшие примеры.
В BSD системах в /usr/share/doc были подкаталоги psd, smm, usd, в которых файлики (ascii с консольным хайлайтингом), прочитав которые, можно было что-то уложить в голове. Я их тоже потом прочитал (похоже, в отличие от большинства коллег;)) Но именно иерархического источника с быстрым поиском не было — GNU info (texinfo) в этом смысле стало великолепнейшим подспорьем.
Кстати, в этом плане великолепно стал помогать гугл (в отличие от прошлых поисковиков) — именно документация для программистов и админов ищется легче почти любой другой информации, особенно по формулировкам типа «man 2 open». Но это уже когда знаешь слово или можешь хотя бы примерно сформулировать задачу.
4. Из предыдущего пункта — отсутствие нормальной иерархии документов. Впрочем, сейчас это становится достаточно редко: сами средства написания документации стали предоставлять автоматическую группировку. И достаточно быстро это получилось — всего-то
5. Совсем высокий пилотаж — это если в документации есть, как в учебнике, контрольные вопросы. Прочёл главу — попробуй ответить на вопросы. Очень часто оказывается, что прочёл, но нифига не понял, или понял неверно — и вопросы это исправляют:) Но это нужно, чтобы автор уже знал (а перед этим — хотел слушать), на чём обычно спотыкаются пользователи. Или правильно предугадал. Обычно таки перед публичным выпуском есть уже какой-то опыт, по которому можно сделать такие вопросы для первого издания.
Но реально это, наверно, в 1/100 от всей документации в мире, если не реже. Я сейчас и не могу вспомнить ни одного примера.
Резюме написанного. Усилия нужны с обеих сторон, но писатели должны таки понимать, как писать, чтобы их читали, а читатели — хотеть освоить, а не просто решить сиюминутную задачу и забыть. Иначе будет, как в анекдоте про революционную ситуацию в постели.
«Задание на JIRA» — тут подмножество тех же проблем. Одни не умеют писать, чтобы их поняли, вторые хотят, чтобы им разжевали.
После какого-то круга граблей обычно приходят с 1000 глупых встречных вопросов. Но это лучше, чем если бы вообще не приходили.
Лень было? ну и писать надо так, чтобы читать хотелось, а не другое)))
Вы не поверите наверное, если я скажу, что чтение документации для меня мало возможно в силу простого ограничения. Я запоминаю не более чем несколько предложений. Как только переверну страницу — уже все забыл. Но бывает так не всегда — а только когда я пытаюсь вкласть в себя что-то совершенно новое, чем раньше никогда не занимался и более того — возможно что и не стану в будущем этим заниматься. В этом случае все особенно тяжко — «смотрю в книгу — вижу фигу» Три предложения без примера использования и все.
Один солюшен архитектор мне сказал в кулуарах: а что девелоперы — они вначале стонут «дай спеку», а потом ее все равно не читают!
Утрировано и обобщено? Да! Но нету дыма без огня.....
В контексте тасок в Jira\ спецификаций в Confluence — есть там есть действительно что читать — то надо «заставлять»: говорить об этом на ретроспективах, привлекать тимлидов и ПМов чтоб доносили смысль что на это «чтиво» идут ресурсы (дорогие в принципе), если разработчики приходят с вопросами по задаче\фиче — то не обьяснять им на бумажке или на словах, а открывать вместе с ними это описание и там его находить и пальчиком туда тыкать, несколько раз спустя время пускать задачи без спецификаций вообще — таким образом давая им «кожей» почуствовать разницу в задачах со спеками и без, если сам принимаешь функциональность — то на теже acceptance_criteria заварачивать задачи назад в «in progress» — желательно в последний день спринта :) - результат думаю понятен, при наличии acceptance_criteria и потраченного времени — задача не закрыта разработчиком, задать этот вопрос им напрямую "почему не читатете? для кого пишу ночами безсонными? :)
Ну т.е. работать с людьми гибко нужно и творчески :)
НО!!! Быть готовым к обратной реакции:
— твои требования непонятны — нужно подстариваться под формат изложения, искать компромис
— твои требования чрезмерно сложны и обильны — нужно искать более короткие и простые формы, добавлять больше диаграмм и визуального материала
— в всей компании\проекте — ты один пишешь документацию (остальные не пишут — полный срам и эджайл :) ) - нужно на этом уровне поднимать культуру уважения к требованиям и документации, а это сложно и тяжело толкать одному огромную баржу
— нужно постоянно актуализировать содержимое, с учетом особенностей реализации, твоих ошибок в дизайне\спеках, с учетом пропущенных требований и т.д. — показывать что для тебя важна суть и качество, а не типа отчитаться что ты к началу спринта подогнал кучу, а потом забил
— возможно ты просто хреновый аналитик — и просто пишешь тонны ненужного контента :)
— для профилактики перечитывать свои старые спеки (которые ты забыл) — ты можешь удивиться — но не так уж они понятны...:)
Готов?
Если делать примерно так — люди потянуться....ИМХО из моего опыта
Пока иду по пути чтения с разрабами доки и тасок — когда вместе читаем то им понятно, подставлять команду не могу так как я за них отвечаю, так что это не вариант.
«подставлять» — как то я такого не советовал. Просто нужно разобраться с ними в сути — им облом/они не привыкли/а зачем или у них есть какие то аргументы. Если в последнее — то конструктивно обсудить коллективно и прийти к чему то, ну а если первое — то значит они еще не зрелые люди в этом плане, тогда жизнь сама им поможет...
Если конечно тебя интересует это «почему» из твоей темы просто для поболтать — то не думаю... врядли из разрозненных ответов разных людей (не с твоей команды) можно понять самую главную причину.
Всегда читаю до тех пор пока не получу целостную картину.
Мені, наприклад, дуже важко заходять Microsoft docs. Наче все розписано у пристойному обсязі, а буває прочитав всю сторінку і не розумієш не те що способи застосування, а й що воно таке взагалі. Звичайно, можна зіслатися на мій низький рівень англійської та недостатній рівень технічної підготовки, і я навіть сперечатися не стану, але:
1. Читаючи статті та інструкції з того ж .NET на інших сайтах, стає набагато зрозуміліше.
2. Офіційна документація інших технологій часто сприймається без проблем і з першого разу.
А зараз читаю «CLR via C#» Джефрі Ріхтера, і теж дуже важко йде. Єдине, помічаю, що просуваючись розділами вперед, краще починаю розуміти попередні частини. Тому, мабуть, краще її спочатку всю осилити, аніж перечитувати одні й ті ж абзаци знову й знову, як я це робив напочатку.
Мій висновок наступний: Microsoft пишуть свою документацію для високорівнених спеціалістів, що знаходяться на межі між людиною і роботом. Можливо вони пишуть для самих себе, без огляду на новачків та джуніорів, що лише починають дертися на цю скелю. І це, певно, на рівні корпоративної культури, бо не залежить від конкретного автора чи носія.
Наверное, стоит сделать уточнение, что не читают документацию в странах пост-совка. Во всяком случае ее там не читают значительно более активно, чем в той же Германии, Скандинавии или даже Китае.
Причем это касается не только инструкций к софту, но и законов. Нашему человеку чем прочитать несколько нужных статей закона, проще задать вопрос на 3х форумах и перечитать десятки страниц мнений и неизбежного срача и говнометания коментаторов.
Внимание, ничем не подтвержденна теория! Корень собственно в совке. Суть которого применительно к законам и инструкциям состояла в том, что написано одно (для внешнего пользователя — красиво, демократично и т.д.) в то время как реально система функционирует по «телефонному праву». Любая попытка отстаивать свои права воспринимается исключительно негативно и называется «правокачанием». В большинстве случаев — наказуема. Более того, поведение согласно писаным законам могло (и может до сих пор) без учета «правового обычая» привести в тюрьму на долгие годы. (Как известно, более 50 тыс. человек в Украине с 2007 года осуждены за нарушение несуществующего закона со сроками до 10 лет по ст. 263КК. И практически вся власть с этим ОК)
Собственно, эта двойственность, когда формально написанному верить нельзя, а реальные правила поведения можно узнать исключительно в устной форме, за почти 100 лет сформировали и укрепили эту традицию. (Надо сказать, что до этого было немногим лучше. «Закон что дышло» пословица древнее большевиков. Но тогда и скилл чтения вообще не так чтобы сильно укоренился. Про доступность любого рода инструкций и говорить не стоит. Поэтому правильнее говорить, что традиция нечтения нормативных документов не сложилась, а просто традиция чтения не сформировалась).
Странно. Прошел по комментариям, но не нашел «а я читаю документацию». Нужно исправить.
А я, вот, читаю документацию. Это первое, что я читаю перед тем, как начать работу с чужим кодом. И таски в жире тоже читаю. И стек оверфлоу. А потом ищу хотя бы несколько примеров реализации нужного мне функционала используя новую для меня библиотеку. И так далее. Мне важно понимать что там происходит перед тем, как я начну использовать новый для меня инструмент.
Если документации нет, то, как правило, либо разбираюсь по коду и пишу для себя доку, либо просто не использую.
вот в том и фишка, есть несколько людей которые нормально отписали, большинство просто сходу сгенерило отмазки
Я сегодня прочитал тикет, прочитал связанный тикет, загуглил официальную доку на библиотеку, исправил 1 строку и добавил еще 2. Потом мне скинули пол гига логов, почитал их, удалил одну из 2 добавленных строк. Не то, что бы она мешала, просто была не нужна. Баг решала одна одна добавленная строка. Ее можно было добавить исходя из текста тикета, без чтения всего остального, но хотелось убедится, что все правильно. Было потрачено пол дня на все.. Если у вас так же можно потратить время, на чтение, то вопрос в разработчиках. А если же у вас все нужно на вчера, и за чтение доки нужно будет выходить в выходной, ведь «ты же всего 1 строку добавил» то какие вопросы к разработчикам..
Ну для меня это звучит как час-два работы, это норм на пофиксить багу, за исключением если это не блокер, а релиз должен быть сегодня
Вот, я говорю пол дня, Вы говорите час..
А потом — почему доки не читают..
а тести прогнати, скільки часу ще займе?
Стривайте-но, ви задали питання: "
Почему так сложно читать документацию?
«, а тепер нарікаєте, що отримали на нього відповіді? Я також почитав коментарі, написав свій. Мінімальна кількість людей написала «я не читаю, бо StackOverflow економить час», решта ж просто з власного досвіду, чи-то з припущень, відповіла на поставлене запитання.
Знаєте, тут як у Гуглі: результати пошуку будуть залежати від формулювання запиту.
Вообще по существу написало пару человек, ибо когда пишут что не читают доку бо ее нет, полностью расходится с вопросом который подразумевает наличие вменяемой доки, и джиры с нормальным требованиями, но коменты были по типу её плохо пишут что полностью расходится с темой — так что это не гугл.
Погано написана документація або її повна відсутність — також причини, чому люди змушені шукати альтернативні джерела інформації. У мене в компанії є інтерфейс взаємодії з промисловими контролерами. У відкритому доступі інформації майже немає, а вмонтований «Help» досить поверхневий. Набагато простіше під час обговорення ТЗ з інженером, попросити його показати вкладення і поля, за якими я зможу перевіряти правильність роботи того застосунку, над яким працюю.
Звичайно, коли йдеться про глобальні інструменти від технологічних гігантів, я у першу чергу звертаюся до офіційної документації.
Да что там доку, часто задание в Джира не читают хоть там четко написано что должно быть сделано по пунктам.
Хочу задание в Джира, где будет написано, что должно быть сделано по пунктам. А то у меня задания в стиле, вот на этой картинке распознавание не работает, а нужно чтобы работало. Пунктов, как это починить — нет.
Тебе всего лишь требуется выучить несколько многословных эвфимизмов к императиву ПНХ. Очень советую почитать страницы общения саппорта Майкрософта, в частности по багам Скайпа. Я не говорю так делать всегда, но когда надо послать — навык полезный. Иные баги и по три года пинают.
Или вот мои любимые треды — как отучить нативного клиента Dropbox перехватывать кнопку PrintScreen? Основное применение кнопки — скриншот, и соответственно на неё вешаются программы, упрощающие работу со скриншотами. В определённый момент Dropbox решил что он тоже умеет делать скриншоты, разумеется тупо и беспощадно. И чтоб не конкурировать, тупо перехватывает кнопку, безусловно. Функцию скриншота отключить можно, а вот перехват кнопки нельзя, и разумеется он вырывает событие из очереди, не позволяя его увидеть другим программам — по принципу «так не доставайся же ты никому».
Коммент разумеется не об этом, а о том что стоит почитать общение саппорта, как они .идарасят клиентов (в том числе платных), и вежливо быкуют уже лет шесть минимум, хотя это натуральное нарушение закона.
Так у меня все задачи такие. Ну и напарника на распознавание уже год найти не могут. Так что, похоже, я нашел вечный проект.
Найди сам, если он тебе нужен.
Та фиг его знает, я тимлиду сказал найти, он и ищет. Мою ставку он знает.
Microsoft это пример говенного саппорта, но также и пример хорошей документации для разработчиков (MSDN). в бытность мою программером на .NET и Win32 , я активно пользовался MSDN-ом и там были вполне внятные примеры использования АПИ с кусками кода , которые можно копи-пастить к себе в проект :-) . По сравнению с МСДН, документация Оракла по Джаве полное говно
был у меня несколько лет назад опыт с довольно большой британской конторкой.
Прилетает одна из первых моих задач в джире, а в ней: 1) скрин таблицы с админки, где-то 30×10 2) примечание — «не верные данные». И все..
Для того, чтобы только узнать, что же там происходит, почему не так как должно быть и в какой момент ушло около недели!
Следующая задача был примерно такого же формата. Вопрос для знатоков, после какой из них я перестал читать что там написано?)
Вопрос для знатоков, после какой из них я перестал читать что там написано?)
Более интересно, что вы в таком случае стали делать?
Закрывать не читая с RESOLVED WORKSFORME?
Cannot reproduce :)
Багато документації (ІМХО вся RFC) пишеться спеціально так щоб читати її було неможливо, так само як і закони. І робиться це для того щоб поріг входу був дуже високим, і до тих хто «осилив», а по факто просто постійно в тому вариться, незмінно приходили і заносили грошенята.
Ну і некоментентність, невмотивованість і брак часу на написання теж слід брати до уваги.
Все набагато простіше: її пишуть дибіли, які давно вже не розуміють (або й ніколи не розуміли) навіщо її взагалі пишуть, але надресировані писати саме так, щоб виглядало «серйозно», тобто бюрократично. А критерій де-факто один: якщо нічого не зрозуміло, а слова та фрази виглядають наукообразно [читай трансліт слів англійського за методикою «лет мі спік фром май харт»] — це те що треба. Англомовні не кращі — вони беруть терміни з маркетингу і де-факто воно має бути булшитом: виглядати великим та неосяжним.
Власне, в маркетингу це також дибілізм — великим та неосяжним його хоче бачити замовник (найчастіше рішення приймає бюрократ, а не підприємець), а клієнту в результаті з того не зрозуміло аж нічого.
заносили грошенята
молодец ты раскрыл коррупцию в IT, можеш ити подаватся на грант в USAID
1. Он далеко не первый.
2. Сарказм без причины — признак <...>
Всі РФЦ — це просто переказ БНФ словами. Основною метою цього художнього прийому є не ускладнення розуміння тексту, а унеможливлення розуміння його неправильно. Якщо тобі складно розуміти РФЦ, значить ти намагаєшся зрозуміти їх неправильно, і це тобі не вдається.
Чого, власне, і прагнули автори РФЦ.
потому что любо ее нет, либо она безнадежно устарела, либо написана не для людей
в настоящее время наилучший вариант документации для девелоперов это вики-системы типа конфленса, где каждый может обновлять страницу по мере актуальных изменений
изменился адрес сервера базы данных, непрерывной интеграции — пиши в вики!
изменилась процедура деплоймента или инсталляции — пиши в вики!
и тд
только нашими стараниями докумунтация будет актуальной и не бесполезной
касательно документации исходного кода типа javadoc, я считаю их бесполезными
-потому что их генерирует машина а не человек
-они не объясняют сценарий использования , как пользоваться тем или иным API.
-часто они избыточны, при грамотно названных методах и переменных
пример бесполезного комментария
// close connection
void closeConnection()
в настоящее время наилучший вариант документации для девелоперов это вики-системы типа конфленса
не, он стал слишком неудобен для этого
да и не вики он уже
я пришел на своих проектах что лучший вариант
wiki на маркдаун файликах
хоть на битбакете, хоть на гитлабе
хоть просто так
по контролем гита
и удобно держать под рукой, в IDE
правя код, сразу писать и в соответствующий файлик
и запушил сразу, и код, и испраление в вики
потом натравил какой-нить сборщик сайта и получи документацию
а в конфлю надо еще отдельно идти...
в настоящее время наилучший вариант документации для девелоперов это вики-системы типа конфленса, где каждый может обновлять страницу по мере актуальных изменений
Это вопрос технической реализации движка, а не содержания (правил и стиля формирования, требования к наполнению и т.п.)
Например, «обновлять страницу» может свестись к добавлению нового предложения из lorem ipsum генератора.
-часто они избыточны, при грамотно названных методах и переменных
пример бесполезного комментария
В данном случае он хотя бы не мешает.
А если есть что-то хоть немного нетривиальное в работе кода, то начнёт помогать.
Проблема в чтении документаций в основном следующие:
1) документации иногда нету вообще
2) иногда написанное в документации или контринтуитивно или не соответствует реальному поведению продукта.
3) документация может быть оооооочень длинной, и читать ее всю нереально
4) документация может иметь плохое структурирование, вследствии чего найти именно нужный фрагмент в ней можно лишь случайно.
5) нужная инфа может вообще быть не описанной в доках.
Список можно продолжить. Думаю каждый с этим сталкивался, поэтому загуглить готовое решение легче и быстрее.
Думаю каждый с этим сталкивался, поэтому загуглить готовое решение легче и быстрее.
особенно легко найти инфу о конкретно твоем проекте :)
коллеги по компании постоянно строчат подробности в своих блогах о тонкостях реализации.
поэтому погуглил, и нашел готовый примерчик, как подцепиться к потрохам модуля который пилится в другом офисе твоей компании.
как-то на одном проекте поэтому встречали три версии коллекций, от апача, гугла, и выдернутую с какого-то опенсорс проекта.
ну а чего, они не конфликтуют, значит все в порядке.
Ньюанс, о котором внизу сказано: есть (ИМХО глубоко ошибочное) мнение, что программист — это нифига не инженер (за 120 рублей в месяц :)) ), потому и доки ему читать и вникать не к лицу. К сожалению, примерно так думают и заказчики, потому на investigation крайне редко выделяется время и деньги. Как результат: непрестижно, неинтересно и забесплатно... Сложно — неправильное слово :)
доки сложно читать — потому что их никто не хочет писать
вынуждение написания доков приводит к пренебрежению читабельностью и формальностью к процессу производства «документа» -> "док 1 шт. — done -> KPI = 30 шт. — done
Выскажу сугубо свое видение вопроса:
1) проблема в том, что многим принципиально плевать на предметную область решаемой задачи. Соот. и читать нет желание
2) Но даже у того, у кого это самое желание есть очень часто сталкиваются с тем, что документацию писали люди из п. 1
С соот. последствиями для содержания.
да я понимаю, что профессионалом быть не модно, модно бородка и вейп со смузи
Попробуйте нанять профессионала. Из того, что вы пишите пока, что складывается впечатление, что проблема на этапе найма.
ну не только я в этом процессе принимаю участие, и у меня взгляд на рекрутинговый процесс другой чем у остальных.
А это возникает из-за «много экранов» до возраста 20 лет. 1 час в неделю допустим у экранов (любых), чтоб такого точно не было.
нет, ADHD-like поведение задокументировано еще в 18 веке, просто раньше оно лечилось лещом от бати
Вполне возможно. Оно возникает из-за не правильного развития мозга в раннем возрасте (экраны не дают мелкой моторики и понимания 3Д, которое возникает в процессе ощупывания), т.о. нейронная подсеть не сформирована верно, а в будущем она должна стать частью большей сети, т.о. большая сеть тоже не верно развивается, что дает синдром.
В 18 веке могло иногда случаться, но маловероятно, нужны были какие-то мего специальные условия для ребенка — изоляция от мира на ранних годах жизни.
понимание 3д — абстрактное мышление — воображение....
Примерно к 23 +/- годам сети полностью завершены. Причем «доростает» последняя, которая прогнозирует будующее — отсюда столько драм у 5ти курсников «не туда поступил».
І хто встановив, що саме «вірно» і для «чого»?
Никто не устанавливал. Ребенок рождается с двойным запасом нейронов. У него есть много периодов по
Т.о. если он с 1 года у экранов, то выростит идеальный потребитель экранов, который в реальном мире не функционален и не подлежит переделке (90% контента работают на «узнавание», что есть антогонист «мышление» и «концентрация» в мозгу, т.о. сеть для «концентрации» просто не формируются — см. симптомы синдрома). Так и определяем, кто установил и для чего.
Дітину запирали від світу у одній підмайстерні.
Ну, с миром -то он взаимодействовал, мир был представлен молотком, мастером и т.д.
Вы путаете. Для того, чтобы мозг мог учиться, он должен сформировать базовые сети, которые могут учиться. Нейроны ничто -связи все. Так вот — формирование сети идет в раннем возрасте.
Каждый фрагмент сети это «столбик», многослойный нейрон грубо говоря, состоящий из много клеток. Памяти, как в компе у нас нет. Каждый столбик содержит какие-то фрагменты чего — либо. Дальше «гипо...» (забыл термин, в середине мозга штука) содержит ссылки. Вот вы хотите понять «яблоко», в этот момент «гипо» выдает набор ссылок и вы знаете «я знаю что это», дальше по этим ссылкам КОНСТРУИРУЕТСЯ ваше личное «яблоко» из фрагментов из «столбиков». Поэтому ваша память сильно не надежна и ложна в целом.
Так вот в исследовании показано, что еще можно напихать в столбики фрагментов в любом возрасте. Но связи заданы в детстве, а вот они будут определять скорость и эффективность использования частей.
Не готов ответить сходу. Но, первые массовые СДВГ уже взрослые, и так и не «переросли», как ожидалось. Так же в этом году принятны новые рекомендации ВОЗ (которые еще не вступили в силу), которые так же не рекомендуют экраны детям.
Перестают формироватся «зоны». Есть очень характерные зоны в мозгу, например, слуха, зрения, выявления лиц и т.д. Они все на ФМРТ светятся в 1 месте у разных людей, разных рас. Т.е. они генетически определены. И эти зоны должны быть заточены на конкретные задачи. Например, мне китайцы все на 1 лицо, т.к. моя зона заточена на европейцев. Время «заточки» тоже генетически определено. Дальше эти зоны комбинируются в сети более высокого уровня, мыслительные, выявления значимости и т.д. Причем 1 зона может входить в неск. сетей. Т.о. эти сети все антагонисты (поэтому, читая фейсбук, нельзя мыслить).
Потом, для исправления ошибки, может понадобится десятилетия, вместо 1 года изначальной настройки (если это вообще возможно).
Чтение книжки и есть мышление — реконструкция интеллектуальных образов автора (хотя не совсем так, потом еще нужна пауза, часто они случаются во время чтения — когда вы не помните, что только что прочтено — это врубалось мышление. Но тут, видимо, культура чтения. Я читаю всегда с паузами не большими.). В фейсбуке вобщем не так — на 90% котики и демотиваторы, т.е. узнавание образов. Мышление и узнавание — антагонисты. Оба дают дофамин, но котики за доли секунды. Поэтому все и залипают.
В фейсбуке вобщем не так — на 90% котики и демотиваторы
можно смотреть на абстрактные мемы для элиты
Примерно к 23 +/- годам сети полностью завершены
тоесть кто после этого возвраста вкатывается в айти ни на что не способен?
Не так, если ты до 23 лет всю жизнь у компа просидел, то дальше только комп. Всякие сложные вещи, типа одеть штаны на голову или ноги, или руки — ето уже не для тебя. Но то крайний случай, нада реально с 1 года в планшет втыкать.
Всякие сложные вещи
игра на фортепиано сложная вещь?
Не думаю. Сложно научится понимать и любить музыку. Это большая работа.
www.youtube.com/watch?v=WEtwLGT7FLo
www.youtube.com/watch?v=CGIq8d6IgYE
З.Ы, Мне кажется, у нее там план по нажатию клавиш точно есть :) Не выглядит и не звучит, как полный рандом.
З.Ы.Ы Пока вы не спросили про «работу». Она может быть и без вашего сознания. Первый год жизни (преславутые 10000 часов) человек круглосуточно подвергается гравитации и учится ей противостоять. Обратите внимание, почти все начинают ходить в районе 10000 часа от рождения.
Не думаю
хотел бы увидеть видос от вас тогда, темболее раз обезьяна может
Не хочу :) Я вообще музыку и шум не люблю. Иногда слушаю Ореста Лютого, но там музыка не главное.
Я наверно не внятно пишу... учат уже готовую связную сеть. В юности их/ее просто НЕТ. Она должна связаться/построиться. А вот уже потом, вы всю жизнь в нее инфу пихаете. Она ее запоминает путем установления доп. связей м-у ВЫЖИВШИМИ нейронами (изначально их 2х поштучно, потом лишние вымирают). Чем больше вы у ребенка активируете изначальных штук, тем больше выживит. Активация зависит от разнообразия внешней среды. Чем больше выжило — тем потенциально умнее и приспособленнее к неожиданностям взрослый.
Участки мозга вымирают/активируются/связываются не в один момент, там периоды по
Размножаются примерно в центре мозга. Там где указатели на фрагменты.
Но они же двигаться не могут — там и сидят.
Еще раз — сеть перестраивается на основани ВЫЖИВШИХ. К 23 годам число клеток мозга примерно 1/2 по сравнению с 0 годом. Вот эта половина и «постоянно перестраивается» до смерти. Конкретное число 1/2 или 1/4 зависит от ранних лет.
если сытый, то хочется спать, а не учиться.
а я все думал, потому что кровь в желудок вся уходит...:)
прибор использует силу ампера для измерения какой то электрической характеристики, какой замазано, иногда для читания документации нужно иметь какие то предварительные знания
Ну тут объединено по сути несколько видов документации — для юзера, для админа и для инженера-инсталлятора. Для юзера по сути только «подключите и считайте показания».
Это как раз очень хорошая документация из-за минимального объёма :) а чтобы понимать показания, и так нужен школьный курс физики в объёме пары классов, так что тут проблемы необразованного юзера, считай, нет.
А вот когда это растягивается на
Этот прибор примитивен, проще только счётные палочки. А вот чуть сложнее — там мало того что на
Вы не поверите ...в 80х и 90х это примерно так и звучало
«синий провод -> контакт 12, коричневый -> 13»
ГОСТы практически наизусть знали в своей области. Без гугла. Ну или был Василий Палыч, который знал и всегда мог пояснить.
Во-во, с соответствующей ценой обучения. А когда всё усложнилось в сотни раз, я сейчас о программном обеспечении — то оказалось что документацию писать так и не научились, и огромные массивы хороших наработок тонут в дерьме плохого документирования.
На 2 странице не замазали название ГОСТа, из него вытекает назначение прибора :)
Да я и не стремился. Просто затёр название, чтобы преждевременно не шаблонить читателя, дав оценить прелесть бюрократии в написании доков.
Скорее количеством дебилов, которые сидели в иерархии, и порядками в этой самой иерархии. Доки как раз таки должны писаться по эджайлу, и ПЕРЕПИСЫВАТЬСЯ (перекомпоновываться) по вотерфоллу когда проект вышел в стабильность. И вероятно это должны делать разные люди.
У нас же по сей день строго наоборот — софт по эджайлу пишут, а доки приклеивают вотерфоллом, в результате документации в стабильной версии просто не существует. И когда энтузиасты энтузиазм теряют (а так всегда происходит), то некому более адекватно саппортить проект, а недокументиованный проект без саппорта дохнет за год-два.
Почему же, делаются. Просто понимать нужно, что эджайл — не более чем набор принципов, и он не заменяет собой РЕАЛИЗАЦИЮ менеджмента. Особенно если это просто декларация-лэйбочка, а в реале всё делается как привыкли, по методологии Cherrez-Zhoupu
Вивалю ще своє бачення ситуації:
люди не умеют читать документацию
Читати вміють всі, якщо вже змогли влаштуватись на роботу, а от знаходити відповіді на питання складніше.
Якщо під читанням доки ви маєте на увазі процес, коли нова людина повинна ознайомитись із системою і почати її покращувати/фіксати, то це одне, а коли вміти в документації знаходити відповідь на конкретне технічне запитання, то це геть інакше.
Особисто я б навіть розділяв ці доки, тому, що для першого кейсу нам необхідно дати відповідь на питання для чого це все взагалі потрібно і якими механізмами досягається, а для другого випадку нам потрібно дати відповідь на запитання, як саме ці механізми працюють.
І тут ми стикаємось з першою проблемою, що, як правило, доки заміксовані з цих двох і, як наслідок, зростає об’єм, а це вже ускладнює роботу.
Проблема № 2, це те, як зазначали нижче, відсутність наглядних очевидних прикладів з кодом і, якщо потрібно, схемами і картинками.
Проблема № 3, це те, що по докам важко навігуватися. Якщо я досліджую якусь функцію і бачу, що з неї викликається ще три інших, а кожна з них ще може може містити виклики або просто складну логіку, то тут без 0,5 часто не розібратися, доводиться собі в блокноті щось занотовувати, замальовувати і потім ще й це все шукати в коді.
Проблема № 4 Тут я об’єднаю дві проблеми: Не точність доки і її не актуальність. Я ще не зустрічав програмістів, які оновлюють доку відразу після додавання нової фічі або модифікації існуючої. Зазавичай, доки пишуться постфактум і тільки тоді, коли тебе вже примусили це зробити. І коли ти зустрічаєш такий не актуальний приклад, ти вже не підеш в доку наступного разу, тому що будеш думати, що там все застаріло і актуальної відповіді не знайдеш.
Коротше, з доками в ІТ зараз дуже біда і знаючи це люди звертаються до них в останню чергу, хз чи це взагалі колись буде виправлено.
задание в Джира не читают хоть там четко написано что должно быть сделано по пунктам
Це геть інша проблема і не варто її заплітати разом з докою.
Якщо завдання написав інженер технічною мовою, а його прочитали не уважно, то треба зробити виговор або покарання тому, хто не уважно читає, допоки не почне читати уважно.
Інший аспект, таски іноді заводяться не технічними людьми, які пишуть в стилі: «Хочу що б все було гарно» і тоді це «гарно» кожен інтерпретує по своєму і в такому випадку треба піднімати питання про зміну процесів і формалізацію створення тікетів.
>>> доводиться собі в блокноті щось занотовувати, замальовувати і потім ще й це все шукати в коді. <<<
Вот у этого корни растут от работы кратковременной памяти. Когда оно в память не заносится то его и правда надо конспектировать, создавая дополнительный фундамент, зацепку, причем определенную самостоятельно (а это очень важно для мозга, значительно повышает рейтинг процесса и результатов его )
Є дослідження, що середньостатистична людина може тримати в короткостроковій пам’яті 5, максимум 7 речей, решта перетирається новою вхідною інформацією.
Через це розкручувати в голові стек виклику функції більш як на 4 рівні всередину не є ефективним. На 4 тому що треба ще постійно тримати в голові що саме ти шукаєш і навіщо взагалі це робиш.
насчет типов документации — полностью согласен когда-то читал интересную статью об этом в блоге jooq хотел найти сейчас но не получилось :(
но суть там была о 3 типах документации
Technical Overview, Guides/How-To и API reference — и по факту это все что надо
я последнее время по себе замечаю что чаще приходится смотреть в сорсы либ, так как не все описано в доках, но я это обычно делаю после просмотра доки, дальше гугления, и потом иду в сорсы если не нашел ответа
насчет таск в джире — там был пункт что сущность должна быть записана в БД (а это не было)
другой случай конкретная валидация определенного поля — не добавлено (в целом там было 3 валидации упомянута, так что вроде немного)
и почему я смешал воединно доку и джиру — наблюдается это обычно в одном флаконе, то есть те кто не читают доку как правило и джиру не читают
Писав нижче, продублюю ще раз)
Якщо людина принципово не уважна, навіть після неодноразових зауважень і тикання його носом в його неуважність, звільняти. Звісно, якщо це не супер критична людина для проекту, в такому разі, приставити когось контролювати його результати.
Многих прийдется уволить, а это непозволительная роскошь :(
Можна( і я далі абсолютно серйозно, декілька разів виступав ініціатором схожих речей) провести міні-тренінг для всієї команди не залежно від сіньйорності її членів «Як правильно читати і створювати тікети».
Поясню, що я маю на увазі: Спочатку варто проговорити очевидні речі для всіх, типу:
«Уважно, двічі, читаєте заголовок і опис тікету, якщо вам щось не зрозуміло або якесь слово можна трактувати двояко, пишете до автора тікета або техліда і з’ясовуєте, що саме автор мав на увазі, якщо автор недоступний, переводите тікет в стан blocked і берете інше завдання.»
Далі можна, без конкретних імен, розібрати описаний вами тікет, коли людина прочитала не уважно.
Тренінг записати на відео і показувати всім новоприбулим.
а это хорошая мысль, спасибо! я пока собирался провести только несколько one to one с теми кто меня сподвиг написать данный пост, но может идея с тренингом не плоха
Чтобы было легко читать документацию в настоящем, надо привыкнуть читать ее в будущем каждый день. Чем больше в будущем будете пользоваться чем-то тем яснее оно для вас будет в настоящем. Но тут есть подводный айсберг — если внезапно (независимо от вашего желания) у вас не получиться читать эту доку каждый день в будущем, то хоть высвистни — знания будут мимо глаз и мозга (смотрю в книгу — вижу фигу)
А вы думали только от вас все зависит? А вот и нет. От факта тоже. И это самое удивительное, потому что я не понимаю как факт может нам передаваться из будущего. Вот только он передается.
В итоге дока будет хорошо в ум ложиться если и факт и намерение читать доку каждый день совпадут по зависимым от вас и независимым от вас обстоятельствам.
Магия, ага.
Ну ты и тему поднял :)
Я в качестве затравки приведу такой факт. В Unix есть такая софтина под названием sendmail. Кто с ней сталкивался — меня, считай, уже поймёт. У неё крайне нетривиальная и весьма непривычная система конфигурации, происходящая из ряда специфических академических традиций. И вот во время работы в LuckyNet мне надо было её освоить на приличном уровне. Была печатная книжка, хоть и чуть старая, но очень близкое к ней содержимое можно было получить на любой из ближайших BSD систем в /usr/share/doc/smm/08.sendmailop — то есть документация была под рукой аж в двух видах, надо только прочитать. И вот читаю я это и тупо нихрена не понимаю. Один цикл, второй, третий... всё равно без толку.
И тут я ловлю грипп. И вот ситуация: лежу я такой с температурой 39, спать не могу, не штырит, но состояние именно такое, что нечего делать кроме как валяться; делать ничего не хочется, но и скучать — тем более. Взял книгу по sendmail и тупо последовательно читал. И что... где-то на
Ещё пара похожих ситуаций была с прослушиванием Башлачёва (кто знает — у него большинство песен пронзительны настолько, что серьёзно слушать их это мини-катарсис), некоторыми книгами. «Моби Дик» в пионерском лагере в пост-чернобыльском летнем изгнании — делать нечего, а у неё... 5/6 неинтересны, но без них последнюю часть не понять; 1/6 — приключения, события, но что и зачем — без первых 5/6 не понятно, кто, зачем и почему; я раз 5 её начинал, бросал и возвращался. Прошёл в итоге только потому, что понял, что иначе не получится. Книга очень понравилась :)
Кто-то может счесть это чуть ли не рекламой всякой химии для вхождения в состояние спокойного освоения. Я никак такое не поддерживаю; наоборот, считаю, что надо воспитывать в себе такое умение просто как естественный метод. Но факт — то, что огромное количество людей слишком нетерпеливы, чтобы спокойно читать и понимать, сосредотачиваться на одной теме и думать над ней продолжительное время. Вообще это считается проблемой тех поколений, что сейчас 20 (в крайнем случае, 25) лет и младше (слова типа «клиповое мышление» и т.п.), но очень заметно было и раньше. Если такой человек заинтересован разобраться, он потратит больше времени (из-за переключений), но разберётся. Если нет стимула, необходимости — он тупо забросит тему, выкрутившись простейшим образом (как то же копирование с SO) и ничего не поняв.
Второй, встречный вопрос — это качество и стиль самой документации. Здесь типовые проблемы:
1. Неупоминание того, что очевидно для пишущего, но никак не будет таким для типичного читающего. Например, даётся просто список функций в духе:
create_foo() - создать красную зюку
create_bar() - создать синюю зюку
zuka_run() - заставить зюку бежать
Что такое зюка — тебе не расскажут. Для автора очевидно — он рисует зюки уже 10 лет. Ты же пришёл сюда за средствами управления кузявостью бутявок. Что зюка это правосторонняя бутявка, или правосторонняя чуняхва — ты не знаешь и узнать это не так просто (поиск в гугле будет засорён так, что не найдёшь).
Точно так же ты не будешь понимать, почему красная зюка зовётся foo, а синяя зюка — bar.
2. При нетерпении читающего к неочевидности обычно примешивается собственная интерпретация на основании того, что очевидно для читателя. Принцип для соответствия читателю называется POLA. Пример из личного опыта:
Есть конфигурация некоторых сущностей, которую надо править руками на
Я: — Ты что сделал? Оно же пишет не то, ещё и ломает соседей.
Коллега: — Ты инструкцию читал? Делай ровно по ней. Вот тут и тут: что писать, куда вводить.
Я: — Ты же сказал, что всё реализовал? Оказывается, не всё, ещё и не так, как нам нужно.
Коллега: — Читай инструкцию! Там всё написано!
Ещё несколько кругов, в которых повторяется одно и то же — он говорит, что всё написано, я — что такая недоделка нафиг не нужна. Коллега всерьёз обижается — он, мол, сверх обязанностей сделал хорошую вещь, а всякие неблагодарные тут...[ольгабогомолец] Я тоже обижаюсь — за хорошо спрятанную в инструкции объёмную свинью и за то, что вместо адекватной реакции на багрепорт (я не хотел благодарности, но хотя бы молчаливого исправления) — «сам виноват, что не прочёл». Ну да, в чём-то я был виноват. Надо было включить режим юриста и вчитываться в каждую букву, но мне тогда это было непривычно, да и сейчас — можно так делать, тратя на это заметные усилия, но как хорошо, когда это не нужно.
TL;DR: когда пишешь для другого, надо иметь хотя бы элементарное понимание, как твой выхлоп будут читать и понимать.
Обычно при нормально настроенной обратной связи в этом случае появляется ряд замечаний с явным подчёркиванием каких-то особенностей, извинений за legacy (как у конкретного продукта, так и общеотраслевое, типа «не мы придумали этот термин», и так далее). Но если люди не хотят обратной связи, то результат так и останется кривым.
3. Сосредоточение на каком-то одном стиле документации, вместо того, чтобы разобрать лучшие практики и сделать объединение нескольких подходов.
В этом плане мне всегда нравился подход Microsoft — независимо от качества самого софта. В документации у них каждая глава имеет три секции:
— overview — что это такое, зачем нужно, ограничения
— using — как пользоваться, начиная от самых типовых сценариев и продолжая до хитрых особых случаев
— reference — справочник по алфавиту ко всем сущностям
Начинаешь с overview и таки понимаешь, зачем оно такое и вообще нужно ли тебе (хотя можно и промазать — но тогда уже только гугление). Смотришь типовые сценарии, уже есть в голове скелет для заполнения. Начинаешь набивать мясом и прочими причандалами, получаешь что-то близкое к нужному, шлифуешь детали. Всё просто и прямолинейно.
В Unix мире аналогичный подход в одном флаконе представлен обычно у тех продуктов, у которых есть texinfo — документация — её пишут по такому же принципу. А вот до появления info было сильно хуже. Типичный анекдот тех времён:
Крошка сын к отцу-сисадмину пришёл, и спросила кроха:
— Папа, а почему солнце ходит по небу!
— RTFM!
— man что? — привычно спросила кроха.
Так вот, это самое «man что?» было стандартной фразой по несколько раз на дню потому, что инструкцию по конкретной функции или программе можно было ещё понять, но узнать, что такое вообще существует и имеет отношение к данной теме — только добывать опросом по коллегам. Ну или по книгам, которые тогда были крайне редки (какого-нибудь Стивенса мы добывали жуткими сложными путями). Иногда в манах были кросс-ссылки, но обычно неполные и рассчитанные на спеца, который просто забыл в запарке, куда смотреть, но не на новичка. Ну и сами маны были часто написаны так, что нифига не понятно, даже если прочтёшь. Уже позже появилась манера добавлять хотя бы простейшие примеры.
В BSD системах в /usr/share/doc были подкаталоги psd, smm, usd, в которых файлики (ascii с консольным хайлайтингом), прочитав которые, можно было что-то уложить в голове. Я их тоже потом прочитал (похоже, в отличие от большинства коллег;)) Но именно иерархического источника с быстрым поиском не было — GNU info (texinfo) в этом смысле стало великолепнейшим подспорьем.
Кстати, в этом плане великолепно стал помогать гугл (в отличие от прошлых поисковиков) — именно документация для программистов и админов ищется легче почти любой другой информации, особенно по формулировкам типа «man 2 open». Но это уже когда знаешь слово или можешь хотя бы примерно сформулировать задачу.
4. Из предыдущего пункта — отсутствие нормальной иерархии документов. Впрочем, сейчас это становится достаточно редко: сами средства написания документации стали предоставлять автоматическую группировку. И достаточно быстро это получилось — всего-то
5. Совсем высокий пилотаж — это если в документации есть, как в учебнике, контрольные вопросы. Прочёл главу — попробуй ответить на вопросы. Очень часто оказывается, что прочёл, но нифига не понял, или понял неверно — и вопросы это исправляют:) Но это нужно, чтобы автор уже знал (а перед этим — хотел слушать), на чём обычно спотыкаются пользователи. Или правильно предугадал. Обычно таки перед публичным выпуском есть уже какой-то опыт, по которому можно сделать такие вопросы для первого издания.
Но реально это, наверно, в 1/100 от всей документации в мире, если не реже. Я сейчас и не могу вспомнить ни одного примера.
Резюме написанного. Усилия нужны с обеих сторон, но писатели должны таки понимать, как писать, чтобы их читали, а читатели — хотеть освоить, а не просто решить сиюминутную задачу и забыть. Иначе будет, как в анекдоте про революционную ситуацию в постели.
«Задание на JIRA» — тут подмножество тех же проблем. Одни не умеют писать, чтобы их поняли, вторые хотят, чтобы им разжевали.
После какого-то круга граблей обычно приходят с 1000 глупых встречных вопросов. Но это лучше, чем если бы вообще не приходили.
Став лайк, якщо дочитав до кінця!
Во-во, отличная иллюстрация к теме нечитателей.
Тогда ходила шутка, что каждый настоящий админ должен хотя бы раз поправить руками sendmail.cf, но более одного раза это делают только маньяки.
На самом деле, один раз разобравшись, потом не хотелось браться за всякие postfix etc — зачем?
зачем?
По нескольким причинам.
Например, в реале начиная ещё где-то с
Например, у нас была relay_based_on_bestmx — лукапились IP bestmx и смотрелись в мапе наших сетей. Писать в явном виде все домены даунликов было невозможно.
А коллеги на exim просто вписывали хитрое правило в фильтр или раутер и смотрели на наши страдания как на нищих негров.
Ещё он крайне криво держал нагрузку. В какой-то момент совет типа «пускайте демона с -ox1 и параллельно разгребальщик очереди с -ox99 -OMinQueueAge=5m» я начал давать просто на рефлексах, увидев характерные жалобы. А для правильной реализации того же MinQueueAge для адекватного держания нагрузки — не линейной зависимости, а плавного роста — надо было даже не конфиг патчить, а сырцы. Зато после этого плавность поведения просто потрясала.
Ещё он раздавал любое письмо не более чем в один ствол одновременно. Где-то в районе 8.11 ввели split envelope, но всё равно точки сплита были произвольными. А postfix просто тут же раскидывал в 50 (или сколько было в конфиге) своих исходящих коннектов, и ему было пофиг, это одно письмо или разные. В результате время доставки могло сокращаться с часов до секунд. Правда, он под тяжёлой очередью тоже страдал, и мы ему fallback’ом ставили sendmail, который мог дальше жевать это письмо хоть несколько суток. (Исправили этот queue manager в postfix уже ближе где-то к 2003.)
Так что без бутербродов из нескольких систем это работать не могло. Я ещё ставил на одной машине
4. Из предыдущего пункта — отсутствие нормальной иерархии документов.
Ну от в екзіма спек ніби гарно структурований, але коли я вперше в нього вліз — просто загубився. Тому що це не дока, це саме спек, довідник по функціоналу. Він абсолютно незамінний, якщо ти знаєш, що, навіщо і як ти хочеш зробить, але не пам’ятаєш синтаксу. Але в’їхати в саму концепцію екзіма він ніяк не допоможе. Є там на початку коротенька главка про прийом та відправку, але ж м’якотка набагато глибше :) Я дхарму осягнув десь аж після року колупання з екзімом і копирсання в чужих конфігах. Все виявилося простим, логічним і очевидним, але тільки після того, як прочиститься чакра.
В большинстве случаев документация криво написана и устарела. К тому же в ней не всегда есть примеры использования той или другой функции. А в 80% случае информация нужна именно о конкретном случае, когда нужно использовать какую-то одну функцию из нескольких сот. В таких случаях проще или спросить тех, кто решал подобную задачу, или посмотреть не возникала ли у кого-то похожая проблема.
Andrey Rogovsky
Допомагаю знайти першу роботу
в IT для Трейні та Джунів на topizda.to
07.07.2019 11:03
У меня на фрилансе часто были заказы — переписать техническую документацию, приведя примеры работы программы с каждой опцией.
Просто составители техдокументации — ленивые и не всегда снабжают примерами.
Скок за это платят, аж любопытно :)
Andrey Rogovsky
Допомагаю знайти першу роботу
в IT для Трейні та Джунів на topizda.to
08.07.2019 06:40
50 евро/страница
А сколько времени уходит на 1 страницу в среднем? Надо ли добавлять диаграммы?
Andrey Rogovsky
Допомагаю знайти першу роботу
в IT для Трейні та Джунів на topizda.to
08.07.2019 11:38
Уже и не помню. Диаграммы — нет, а вот анимированные гифки, в которых записаны выполнения и результаты — да.
Я уже представляю эту анимированную гифку на 4.99 гигабайта, потому что лень платить за лишние страницы :)
Andrey Rogovsky
Допомагаю знайти першу роботу
в IT для Трейні та Джунів на topizda.to
08.07.2019 14:53
Не, там готовы платить деньги.
Обычно у человека есть конкретный вопрос. Который уже кто-то задавал, и на который есть ответы. Ты вбиваешь вопрос, получаешь почти сразу готовый ответ. Это быстро проверить. С документацией проблема в том, что она даёт системную информацию, и часто для ответа на вопрос надо сочетать информацию из
Иногда поиск по stackoverflow я использую для поиска подходящего раздела в документации. Например, есть какая-то тонкость C++. Эта тонкость наверняка обсуждалась со ссылками на стандарт. Куда лучше, чем пересмаривать все подходящие места из стандарта, и не факт, что не пропустишь. Оно, конечно, полезно, но не быстро.
Потомучто программисты не гуманитарии, не хотят читать простыни, а переходить по возможности сразу к делу. Скорей всего если на работе попадется чел. который внимательно вычитывает всю попавшуюся документацию, то это будет хреновый программист у которого сильно страдает эффективность труда.
Вообщемто поэтому объясняется популярность stack overflow где весь сайт построен по принципу «сразу к главному».
И потом занимаются велосипедостроением и добавлением костылей вместо того чтобы применить адекватный подход. Мне кажется именно поэтому 98% ит проектов такое говно
Потомучто программисты не гуманитарии, не хотят читать простыни, а переходить по возможности сразу к делу.
Так делают не программисты, а говнокодеры.
Смешались в кучу кони, люди...
Какую доку, какую джиру? О чем вообще речь конкретно? И кто вопрошает?
Edit:
Ок, прочитал пару комментариев ТС, которые немного проясняют ситуацию.
доку библиотек/фреймворков
Доки библиотек/фреймворков, особенно closed-source, — это чуть реже, чем всегда протухшие портянки, у которых столько же шансов внести ясность, сколько и внести путаницы. За счастье, если в них есть хоть какие-то примеры использования. Вообще джек-пот, если эти примеры чуть сложнее Hello World и компилируются. Это все потому, что поддерживать и развивать доку — это огромный труд, в который далеко не всегда вкладываются. Ситуацию немного лучше в OSS, но даже там чаще делают простой overview API, а остальное отдают на откуп комьюнити во всяких медиумах и том же SO.
есть такие доки — не спорю, но о тех что я сейчас говорю все детально описано на страницах документации.
Возможно эта дока наоборот страдает от излишней громоздкости и детальности в контексте задачи программиста. Грубо говоря, человеку нужен Hello World к концу дня, а дока ему предлагает пройтись по основам теории струн, в том виде, в котором её себе представляет автор доки (привет ffmpeg).
остальные вещи из джира (то есть люди читают заголовок джиры и делают как его понимают — а почти всегда понимают его не правильно)
Ну это вообще дичь какая-то. А что происходило на discovery, когда ваши программисты должны были, по сути, вслух читать текст задачи и задавать относительно него вопросы к PO?
Что происходило на grooming, когда ваши программисты должны были оценивать задачи/подзадачи, которые они, скорее всего, сами же написали/продиктовали, основываясь на обсуждениях acceptance criteria во время discovery?
Ситуация, когда программист приступает к выполнению задачи, с которой он знаком только по заголовку в джире и которую он не оценивал невозможна в принципе. Если у вас такое практикуется, то в топике вы возмущаетесь по неверному поводу.
речь о не июнях
Если на самом деле опытные и серьезные программисты не читают доку и тексты задач в джире, то есть совершенно ненулевой шанс, что проблема таки в доке и в текстах задач в джире. А скорее всего в процессах.
Судя по комментариям таки явление носит более популярный характер чем я думал. Я не указал конкретную доку, но все сказали что дока фигня (за исключением 1 человека), то есть люди не зная кейса уже генерят оправдание почему бы ее не читали.
Печальненько...
кстати недавно (случайно) получилось создать игру против таких людей, был сделан довольно унылый гайд (со скринами и все такое) и я как-то банально добавил к нему contents и разметил что буквально каждый абзац был там отдельной ссылкой.
и потом приходит такой реальный американский разработчик (не знающий славянских мов)
раз, вопрос — я ему ссылку
два вопрос — я ему вторую ссылку
три вопрос — снова ссылка
мы доиграли до 5 вопросов, потом он больше ничего не спрашивал, видно дока оказалась достаточно детальная гг
случай с четверга — товарищ часа два искал ответ спрашивал всех вокруг гуглил стековерфлоу как в либе для валидации (либа популярная и опенсорсная) сделать чтобы для матчинга через регекс пускало «пустые» значения так как обязательное поле или нет хотели определять в другом месте в зависимости от другого поля.
так вот, когда я к нему подошел — единственное что я сделал я посмотрел полной сигнатуру функции для добавления валидации регекс, и конечно это функция имела второй опциональный аргумент который разрешал пускать пустые значения как валидные либо для пустых значений все равно использовать регескп. я потратил на это около 1 минуты — в доке было все описано, доку смотрел через ИДЕ (даже не куда не надо было идти). почему нельзя прочитать доку которая под рукой?
еще был интересный случай — девочка пробовала запустить апач — он валился с какой-то ошибкой и инфой что детали в логах, конечно девочка логи не смотрела и тупо гуглила месседж в интернете и потратила полтора дня, потом когда она пришла ко мне с этим — я прочитал ошибку, увидел смотреть в логах, и посмотрел в логах. в логах была четкая инфа о том какая конфигурация не правильна, и какие допустимые значения — мы это поправили и все заработало без какого либо гугления, и заняло это 5 минут
так что:
метод проб и ошибок нынче работает эффективнее и быстрее
нифига не эффективнее и быстрее, конечно есть плохо написаные доки, но даже в плохо написаной доке инфу зачастую легче/быстрее найти чем не читая ее в принципе
кстати описанные персонажи носят лычку мидл, и имеют амбиции называться сеньорама (считают что их не до оценивают)
Это ошибка выжившего.
А до этого было 1000500 случаев, когда в сигнатуре функции такого не было, но ваш мозг услужливо по контексту подсунул только подходящие случаи из памяти.
просто раньше я меньше плотно работал с людьми, а сейчас намного больше, и начал замечать что люди доку не читают — я прекрасно понимаю что доки бывают плохие (сам писал плохие доки — каюсь, хотя старался, иногда получались не плохие но таковых было меньше, проще было делать презентацию чем доку).
лично я не часто гуглю, а если гуглю то в 95% процентах найденые ответы — говно которое можно только рассматривать как что-то, что никогда не следует делать
я еще добавлю — почему люди вместо того, что бы обсудить вопрос в тексте, начинают звонить и трындеть ? нет, я согласен, когда кнопку надо подвигать на пару пикселей влево-вправо и сразу посмотреть, то в телефонном (слак, скайп, зум) оно еще имеет смысл, но что обсуждать голосом когда надо внимательно подумать ? ну т.е. когда один вопрос «а как вот это лучше сделать» мне нужно минимум пол часа что бы придумать варианты, погуглить конкурентов и тогда только я могу пару тройку подходящих вариантов предложить ...
п.с. что бы был не офтопик — в детстве любил читать доки — вся семья с новым видиком-телеком-машиной играется, а я читаю юзер гайд :)
самые офигенные юзер гайды кстати были от майкрософт, такие толстенные книги на офигенной бумаге, переполненные водой и картинками но очень клево сделанные
но что обсуждать голосом когда надо внимательно подумать ? ну т.е. когда один вопрос «а как вот это лучше сделать» мне нужно минимум пол часа что бы придумать варианты, погуглить конкурентов и тогда только я могу пару тройку подходящих вариантов предложить ...
Тогда так и говоришь — «ok, выделяю на это время, мне нужно 2 часа, жди письма». Но вначале вопрошающий скорее всего не предполагает, что это не мгновенно, мягко говоря.
самые офигенные юзер гайды кстати были от майкрософт,
Да, это они умеют даже лучше своего софта :)
кек
ну чаще всего документация не раскрывает общего вопроса «как этим пользоваться?» posix-утилиты с 100500 параметрами без сквозных примеров — тому яркий пример
если же это за indoor-проект, то там обычно дока — страх, ужас и записки сумасшедшего. без дерганий тимлидов-разрабов за рукава — общая картина никогда не сложится. а в рамках обожаемого и превозносимого всеми эджайла/скрама, «задрачивание доки» — хороший звонок чтобы тебя с проекта/галеры «соптимизировать»
posix-утилиты с 100500 параметрами без сквозных примеров — тому яркий пример
если вы про маны, то там же идея что вы знаете уже что и как , просто нужно подсмотреть правильные параметры, обычно дока есть
вот просто для примера глянул
man ln
info ln
если вы про маны, то там же идея что вы знаете уже что и как
Именно — для тех, кто туда добрался, уже есть половина ответа. А те, кто не добрался — не знают, что такое есть или как зовётся.
Нужно выставлять не просто документацию а функционально полное описание работающего куска кода.
ФПО это видео, кодепен (интерактивный запуск в песочнице), тексты всех определений, несколько примеров (и исходники примеров) и все это легко находится на сайте по ключевым словам.
Из-за дыр в документации. Слепых пятен. Разрывов в семантической цепи. То, что разработчики посчитали само собой разумеющимся в их продукте и не стали подробно описывать. Когда такое находишь в Get started просто вместо слов одни выражения.
Когда такое находишь в Get started просто вместо слов одни выражения.Ось тут підтримую. Коли переходжу до розділу «Get started», то зазвичай розраховую побачити інформацію, розжовану для новачків, які IDE вперше в житті відкривають. А насправді інколи від тебе вимагається солідний бекграунд розробки та хвацьке володіння кількома суміжними технологіями.
Люди всё умеют читать — но зачем?
Когда покупаешь автомобиль — тебе к нему выдаётся руководство/инструкция с подробными описаниями всего, что в этом автомобиле есть, как оно работает, как его включать/выключать и что делать если что. И что — чтобы на нём ездить — будем все 300 страниц читать? Не будем, конечно. И если непонятно, как открыть багажник без ключа — легче в интернете вбить запрос «%carName %modelName %productionYear открыть багажник без ключа» — и тебе сразу выдаст результат, что это скрытая кнопка под рулевой колонкой справа, например. В документации тебе бы пришлось рыться и искать, где вообще про это написано — «Управление автомобилем»? «Навигационная панель»? «Панель управления»? «Багажник»?
СтэкОверФлоу тем и хорош, что там можно что-то спросить «образно» — «Йа джун, почему в пайтоне нету конструкции Switch..Case, не могу найти, што делать». В документации к пайтон3 ответа на этот вопрос нету — потому что незачем — и это самый простой пример.
Соответственно, документацию читают, когда готовятся что-то делать, особенно нетипичное, на основе какого-то класса навернуть обёртку и полезно посмотреть, что оно там будет уметь, а что не будет. Либо хочется просто изучить, что там вообще. Документация больше досуг и изучение, а вот решение рабочих моментов — через поисковичок
тебе к нему выдаётся руководство/инструкция с подробными описаниями всего, что в этом автомобиле есть, как оно работает, как его включать/выключать и что делать если что. И что — чтобы на нём ездить — будем все 300 страниц читать?
Почему нет? Тем более что там картинки, и один круг чтения это минут 10.
Документация больше досуг и изучение, а вот решение рабочих моментов — через поисковичок
В котором, чтобы правильно задать вопрос, надо уже знать от 1/2 до 3/4 ответа.
Почему нет? Тем более что там картинки, и один круг чтения это минут 10.
Если машина напрокат, да еще и мануал на не английском, то только методом тыка и гугление (как открыть бензобак у этой шайтан-повозки)
не умеют читать документацию
документацию по домену проекта или по какому-то инструменту?
доку библиотек/фреймворков и acceptance criteria + остальные вещи из джира (то есть люди читают заголовок джиры и делают как его понимают — а почти всегда понимают его не правильно)
щас все будут ржать с пхп, но у yii2 отвратная дока, и так уж вышло — что у многих стандартных модулей тоже...
то есть вплоть до того, что при развороте скелетона по туториалу — ты обязан совершить еще пару шагов с СО... и вот после 5 модуля подобного — уже и доку читаешь по диагонали
не будут. у нас есть проект на yii1 (который постепенно пересоздаем на laravel). и там ... уффф. ну неудачный фреймворк, не первый и не последний гг
Потому что писать её должны те, кто умеет делать. А не те, кто думает что умеет писать. В последнее время документацию вообще пишут маркетолухи.
Любимый тест для самопроверки: Найди название любого свежего фреймворка, о котором раньше не знал. Важно, только название. Пойди на сайт этого продукта, и в течение
есть такие доки — не спорю, но о тех что я сейчас говорю все детально описано на страницах документации.
и обычно те же люди ни читают джира — хоть так могут быть acceptance criteria очень хорошо описаны — люди тупо игнорят и не читают
о тех что я сейчас говорю все детально описано на страницах документации
Скажи где, я туда работать пойду.
Основная проблема документации — каждый её кусочек написан так, будто ВСЁ ОСТАЛЬНОЕ ты уже вызубрил. Даже в случае гиперссылок это решает проблему только наполовину.
Хорошая документация должна быть избыточной. Если на что-то особое ссылается, нужно кратко объяснять это НА МЕСТЕ, и уже за подробностями отсылать гиперссылками. В большинстве же случаев гиперссылок нет как таковых, а если и есть — то в стиле «смотри также wjeahibnfd, eflsjf, gtcfhdjs» в конце абзаца, как будто если я не понимаю этот кусок доки — мне поможет замусоривание памяти другими, особенно если эти ссылки оставил не автор, а робот, тупо найдя ключевые [с его точки зрения] слова.
люди тупо игнорят и не читают
За таке треба дрючити і звільняти, якщо не лікується після
Нащо такі складнощі? Залишити на овертайм все виправляти, що зроблене не за RTFM.
Как показывает моя практика работы в интернациональном коллективе, иногда даже лучше, когда не читают, потому что многие (реально многие не-нейтевы) умудряются прочесть то, чего нет и понять совершенно не так, как написано. И при этом быть абсолютно уверенными, что они сделали всё, как надо.
и какие решения такой проблемы? отсеивать всех кто ниже настоящего B2?
Отсеивать врядли, потому что тут много таких граждан, а на гражданство тут нужен IELTS пятёрочка (был по крайней мере), а это чуть выже понимания command language. Самое эффективное, наверное, блокировать таким карьерный и зарплатный рост. Чтение и понимание прочитанного должно быть в пререквизитах к миддловской позиции. За несоблюдение персонально дрючить, дрючок дать тимлиду.
K сожалению, к большому сожалению, таски в джире, а, порой, и саму внутреннюю документацию пишут те же люди, что и читают. В результате напишут чего, и хорошо, если не понял — в большинстве случаев можно подойти и в рабочем порядке выяснить что имеется в виду. Но плохо, если понял формально правильно, но совсем не то, что имел в виду пишущий.
Может проще писать надо, без ухода в «заумную» терминологию, вся суть которой имитировать наукообразность текста?
Слабо верится если честно. Обычно июни без опыта таким только страдают. И то непродолжительное время.
Ну странно, обычно программеры внимательны к тому что написано в жире и фанатично делают как там сказано. Задрачивать кого-то до попыток разобраться самому сначало тоже как-то не приветствуется.
мне просто последнее время персонажи попадаются с обратным attitude
Valentin Nechayev
Ciemna noc
Олег Дорожко
anonymous
Eduard Voloshyn
poc
Stanislav Fedenko
Luci
anonymous
Yuri Predborski
Александр Шевченко
Alexandr Gavriluk
Олексій Пєніє
Alexandr Gavriluk
Aleksandr Marchenko
BodjaSyper
Dmitry Panfilov
Артем Перекресний
Victor Mikhaylov
Sergey Lysak
Dmitry Bugay
Євген Лесько
Дмитро Дем'яненко
Dmitry
Dmitry Panfilov
Oleksiy Zakharov
Олексій Пєніє
Ювженко Денис
Олег Дорожко
Valeriy Zamaraiev
Nikola Utiuzhnikov
Andrew Sevastianov
DNA Exp
Андрей Петров
TechnoBarbarian
anonymus ps
Сергій Мацюпа
Galkin Roman
Дима Дима
Mike Gorchak
Nikola Utiuzhnikov
Дима Дима
Найкращі коментарі пропустити