— Ну, там можно научиться огромному количеству новых и неизвестных вещей.
— А… Правда? Ок, удиви меня.
— Вот! – наивный юнец с радостью ткнул на указатель на приборной панели своей «Хонды».
— И что же в этом такого прикольного?
— Видишь стрелку? Она показывает с какой стороны у тебя крышка бензобака, чтобы ты помнил, где останавливаться у бензоколонки.
Я тяжело вздохнул, открыл бардачок, и, к ужасу парнишки, извлёк из него потрёпанный мануал 2004 года выпуска. После 20 секунд листания оного мануала, я ткнул пальцем в ту самую иконку, которая показывает, с какой стороны у тебя бензобак.
— Ну вот, пожалуйста. Это было известно ещё до «Тик-тока», и даже до «Фэйсбука». Эх! Это было известно ещё до интернета и, возможно, до появления автоматической коробки передач. Это было известно до того, как твои родители появились на свет. Ты мануал-то читал?
— Нет.
— Оно и видно.
Признайтесь, люди не читают мануалов. Давайте посмотрим, что Вам можно посоветовать, чтобы люди от них вообще избавились.
Я принадлежу к той странной внеземной расе, которая с удовольствием читает сервисные мануалы.
Возможно это произошло потому, что с детства я помнил, как мой дед постоянно возвращал к жизни старый телевизор «Фотон». Ящику было уже более 30 лет, и ломался он с завидным постоянством. Раз в год мой дед доставал отвёртку, паяльник и кучу интересного инструмента. После этого он залезал специальным щупом в трубу, и я слышал жуткий «бах». Это он так разряжал основной конденсатор, чтобы потом не убить себя всеми этими вольтами. Но самое интересное начиналось потом. Внутри самого телевизора лежала ОНА — принципиальная схема. Я просто не мог оторвать глаз от этой восхитительной карты микромира, которая казалась мне такой загадочной и непонятной, но при этом, точно проводила моего дедушку через все закоулки электронной страны. Пару тычков щупами обычно быстро находили пробитый конденсатор или сгоревший резистор. После чего ящик возвращался к жизни и продолжал служить, давая фору марсоходу Curiosity по количеству дней, прожитых после окончания срока службы.
А возможно всё было по-другому. Когда мы учились программировать на компьютерах в универе, интернет не представлял собою бесконечную базу данных любых знаний. Самым-самым был дорогой и любимый MSDN. Библиотека всех знаний Microsoft носилась с собою на каждое занятие, и Великий Хранитель Подписки был тем самым друидом, раздающим знания всем тем, кто хотел учиться и познавать новое.
MSDN читался ради удовольствия, и для того, чтобы выпендриваться перед учителем (привет, ceba!), показывая умение пользоваться изощрёнными функциями и давая доступ ко всеми любимому «зачёту автоматом».
Позже, по долгу службы, я не раз натыкался на «островки знаний». manualslib.com всегда являлся поставщиком заветных сервисных мануалов. Тех самых, невообразимо объёмных мануалов, которые описывали все внутренности принтеров, телефонов, схем и контроллеров. Тех самых мануалов, которые позволяли добраться до последнего соленоида, в котором прогнивала резинка, из-за которой дох принтер за 2000 долларов.
Когда я вёл команду джунов, которые должны были разбираться с Docker swarm я с интересом отвечал на их вопросы путём копи-паста ссылок из документации Docker. У меня не было идеи о том, что кто-то возьмётся за Докер, без хотя бы быстрого перелистывания этой документации, как минимум для того, чтобы знать, где и что лежит.
Люди не читают мануалов. Причин тому несколько.
Во-первых, в среде разработчиков сейчас существует идея о том, что заставлять пользователя читать мануалы — это зло. Мы ненавидим тот факт, что открывая наше приложение, пользователь не начинает сразу же покупать нужные нам сервисы или жать на нужную нам кнопку. Максимум, что мы можем дать нашему клиенту — это быстрый экскурс в список основных кнопок, путём вынуждения его кликать на эти кнопки.
Во-вторых — панический страх мануалов. Инструкции превратились в талмуды, которые выглядят одинаково удобочитаемо до и после шифрования. Что бы ни делал пользователь, ему неинтересно/нет времени/нет желания. Мы с вами живём на другой планете. Мы привыкли к тому, что, если функция не возвращает то, что от неё требуется, то мы будем лезть в docs.[nameofthecompanygoeshere].org. После прочтения кучи текста, мы вникнем в то, что шестой параметр должен быть ненулевым и заставим-таки эту штуку работать как полагается.
Но, даже в рядах инженеров и программистов появляется всё больше и больше тех, кто предпочитает stackoverflow вдумчивому пониманию предмета.
Итак, давайте разберёмся, как же сделать так, чтобы Ваш мануал канул в Лету, и как сделать так, чтобы Вам постоянно названивали в три ночи, когда всё легло.
▍ Композиция
Если Вы уже решились
Написать талмуд великий,
Чтобы всем на предприятье
Всё подробно рассказать,
Не спешите Вы нисколько
Всё раскладывать по полкам,
Начинайте где попало.
Лишь бы было что сказать.
Вот несколько наиболее отвратительных примеров в этой категории. Калифорнийский справочник водителя. Это моя любимая книга «для поржать», если очень сильно хочется. Помимо того, что она написана вразнобой, она ещё и переведена машинным переводом. Поэтому скатиться под стол со слезами можно просто так, без особых усилий. Что же тут такого интересного?
В отличие от Москвы, где Вам предлагается пойти в автошколу, выучить правила, а уже после этого идти учиться водить, в Калифорнии другой подход. Вам надо будет изучить эту книгу, пойти в местный офис по делам транспорта, сдать экзамен, типа «выбери правильный ответ», и тогда Вам дадут разрешение на вождение.
С этим разрешением Вы можете в течение года делать что угодно и водить всё что подходит под вашу категорию машин, но только при наличии в машине кого угодно с правами. И вот только после этого Вы можете идти и сдавать экзамен. (Хе-хе, а потом жаловаться, что на дороге полно идиотов).
Ну так вот, эта брошюра занимает 120 маленьких страниц текста и читается за 30 минут.
Но, первые 40 страниц текста занимает куча мишуры, что, да как делать с документами и к какому окошку подходить. Особое внимание уделено тому, что нельзя оставлять животных и детей закрытыми в машинах на автостоянках, ибо они от этого умирают. (Действительно, проблема с этим есть, но для сравнения, это лишь 20 смертей на автостоянках из 3500 смертей на дорогах за год.)
Информация о том, как, собственно, водить машину, начинается на странице 58. В середине книги.
Или вот. Возьмите любой мануал к Вашему автомобилю. Там тоже можно повеселиться. Для начала Вам приходится читать о том, как правильно устанавливать ремни безопасности для транспортировки младенцев. Несомненно, родителям малышей эта информация очень полезна, но это не 100% всей аудитории. Что самое главное в машине? Она должна ездить. Информация о том, как сделать так, чтобы она поехала, начинается примерно после 120 страниц информации о том, как она ломается и как её не нужно обслуживать.
Другой пример такого мануала — это документация по языку Rust. Об этом я уже писал. Первая глава полностью погружает читателя во все тяжкие языка. Но понять первую главу можно только изучив четвёртую… Дилемма…
Давайте посмотрим на что-нибудь приличное. Вот, например, мануал к микс-борду фирмы Mackie.
После одной страницы инструкций о том, как не убить себя током, Вам будет предложена картинка, которая покажет, как подключить гитариста, басиста, барабанщика и солиста и начать лабать Deep Purple с размаху. На следующих страницах последовательно разбираются примеры и описание неудачных случаев (например, неправильно спаянные провода). В конце документа приводятся все технические данные и псевдодиаграммы, со всеми ТТХ инструмента, то бишь, всё особо заумное.
▍ Номенклатура
Если Вы писать решили
Мануал большой и толстый,
То не парьтесь со словами.
Называйте как попало.
Если юзеру вдруг нужно,
То ответ нароет сам.
Тут в пример можно привести один из самых страшных мануалов, которые мне довелось читать в моей жизни. NEC Univerge Phone System Programming.
Согласно Вики-словарю, номенклатура — это перечень названий, терминов, категорий, употребляемых в какой-либо отрасли науки, техники.
Ну так вот. Этот перечень возможно где-то и существует в глубинах компании NEC (чтоб уже этих япошек!), но добросовестным инженерам он недоступен. Например, если Вы откроете мануал на странице 246, то Вы увидите инструкции о том, как программировать ICM Key на телефоне. У Вас не будет ни малейшего понятия, что такое ICM Key. Инструкция об этом умалчивает. Думаете всё так просто, пойди и погугли? Ха, ага! Идите, попробуйте погуглите это, так, чисто по приколу. Вы увидите, что эта аббревиатура используется только инженерами NEC и никем другим. Нагуглить это будет невозможно. Просто нет никакого варианта найти эти данные в интернете. Надо будет звонить в техподдержку для инженеров, и общаться со специалистом. Если повезёт, Вам ответят.
С подобными проблемами обычно сталкивается не Вася, который решил выучить NPM за 20 минут на ютубе или Петя, который гуглит «как решить алгоритмы на собеседовании» на stackoverflow. С такой проблемой столкнёшься ты, хабраюзер, когда пойдёшь работать в реальную контору с реальными людьми. Серьёзные enterprise системы всегда достаются Вам с пачкой слов, которые никто за пределами этой системы не использует.
Название серверов, сетей, платформ и систем, которые были Вам родными последние 5 лет, пока Вы работали в ${user.CompanyName}, приелись настолько, что Вы уже не можете поверить, что кто-то об этом не знает. Некоторые про это просто не думают. Например, слово FTP может означать не протокол передачи данных, а конкретный сервер.
ПНСВ, Desktop, Та-самая-карточка, The Server, это всё те странные обиходные слова, которые непонятны никому за пределами Вашего круга общения.
Более того, даже слова, которые можно найти в словарях, могут представлять для читателя определённые трудности. Некоторые термины можно понимать двояко. «Обжиг» можно производить как в печи, так и с помощью горелки.
▍ То, о чём вы говорите
Если в новом мануале
Говорим о тахионах,
То не стоит торопиться
Тахионы показать
Юзер нынче очень круто
Может сам всё рисовать.
Меня охватывают страх и трепет, после того, как я вспоминаю об одном сервисном мануале принтера. В нём не было ни одной картинки.
- Снимите переднюю панель.
- Увидите 6 шурупов, открутите их.
- Снимите боковые панели.
- Справа Вы увидите два шурупа и три гайки.
- Поверните принтер на 90 градусов по часовой стрелке, найдите шуруп под пружиной номер 85, и открутите его. Это отпустит систему держателя номер 10, которая удерживает барабан…
Ну и так далее.
Можно сколь угодно долго объяснять пользователю, где этот шуруп, но проще будет показать. С другой стороны, перегруз текста картинками может всё усложнить.
▍Самая главная идея вашего мануала
Тут вредного совета не будет. Тут сразу можно перейти к самой главной идее. Как надо писать инструкцию?
Для начала, ответьте себе на вопрос — для чего существует Ваш продукт/изделие/система? Какова её цель? Самая основная цель.
Автомобиль — это техническое средство, предназначенное для быстрого перемещения по дорогам.Стиль не важен. В некоторых компаниях за стиль будут сурово наказывать, а в некоторых можно рикроллить всех направо и налево. Важно, чтобы Вы могли сформулировать описание своего продукта в одном предложении.
Машина позволяет быстро перемещаться по дорогам.
Эта система позволяет Вам получить доступ к данным Вашей кредитной карточки через телефон.
Продукт представляет собой мультитул для анализа безопасности информационных систем.Самое главное — это передать идею того, что на самом деле будет происходить на следующих 100 страницах.
После этого, всё, о чём Вы говорите, можно основывать на этой мысли.
Автомобиль надо уметь водить. Для того чтобы его водить, надо уметь работать с основными элементами управления, такими как руль и педали. В том числе Вы должны знать и понимать, что означают различные приборы на панели управления.Это то, что приятно читать, и что самое главное, это то, что можно читать.
Внимание! Вождение автомобиля связано с риском, и неправильное использование может привести к летальным последствиям. Обязательно ознакомьтесь с данными о безопасном вождении.
Правильный уход за автомобилем гарантирует его работоспособность… И т.д.
Почему мы начинаем статьи на Хабре с хорошо продуманной КДПВ и отличного введения, а наши мануалы выглядят как ужас, летящий на крыльях ночи?
▍Зачем вам всё это?
Если вам охота очень
В воскресенье спозаранку
Получить звонок от босса
На мобильный телефон,
И, забив на выходные,
Бодро броситься в контору,
Гордо взяв клавиатуру
Побежать всё поднимать,
Не пишите мануалов.
Много помощи не будет.
Лучше Вы на всё забейте.
Всё само собой пройдёт.
Хорошо написанный мануал — это то самое чудо, которое сохраняет Вам нервы и время.
Когда Вы ловите себя на том, что в очередной раз объясняете, как и почему что-то работает, то пора садиться и писать.
В мире есть люди, которые могут за день выдать 20 страниц текста. А есть и такие, которые приходят в тихий ужас просто от необходимости написания е-мейла.
Если Вы принадлежите к последним, то подумайте вот о чём. Написанные Вами слова — это Ваш аватар. Это Ваш виртуальный помощник, который заменяет Вас перед толпой, пытающейся достать Вас вопросами.
Не парьтесь по поводу того, что у Вас нет стиля, и Вы не умеете писать. Если у Вас есть система для ввода текста в компьютер, то у Вас есть всё, что Вам нужно.
Садитесь и пишите. После этого, прочитайте то, что Вы написали и пишите ещё. Дайте это почитать несведущему человеку, посмотрите, сможет ли он понять, что Вы написали.
Главная цель мануала — сделать так, чтобы кто-то другой мог выполнить определённые действия.
Вот и попытайтесь добиться этой цели. Предложите Ваш мануал ничего не понимающему в этом вопросе человеку, и посмотрите, сможет ли он выполнить инструкции, которые Вы описали?
Не надо пытаться сделать видео- или аудио- книгу. Видео занимает намного больше времени для производства. Аудио зачастую бесполезно. Более того, мне лично очень скучно тратить время на просмотр видео. Текст воспринимается намного быстрее, чем видео. И если мне нужно с чем-то разобраться, это намного проще сделать, когда у тебя в руках есть текст.
Видео очень полезно, когда мануал уже написан, особенно для иллюстрирования сложных компонентов систем.
Wiki — это зачастую хорошая идея для сохранения ресурсов мануала, но она не отменяет того факта, что у Вас должен быть приличный текст, который можно прочитать от начала до конца.
Короче, если Вас запарили постоянными вопросами, и Вы чувствуете себя задёрганным, то возможно пора уже сесть и написать этот мануал.
hanselman.com — вот один из примеров. Каждый раз, когда к Скотту приходят и задают глупые вопросы, он пишет статью в свой блог. В итоге у Вас есть блог, и повторяться не приходится.
Пишите. Это замечательное умение. Как раз потренируетесь.
Комментарии (142)
dlinyj
08.11.2021 12:50+35До чего шикарная статья! Я из тех, кто не очень любит читать, но довелось много писать мануалов. Самые классные мануалы я писал в оборонке, это были ТУ, ПИ и прочие подобные документы. Мы делали очень сложное техническое устройство, принцип работы которого без специального образования понять было сложно, но передавали его в руки военных, которые могли представлять из себя обезьяну, которая умеет читать и выполнять что написано. Да простят мне такую аллегорию, но смысл в том, что мы считаем что человек исполнитель, умеющий читать.
И вот, умение написать грамотную инструкцию, чтобы её мог повторить любой умеющий читать исполнительный человек. Это было круто. Представитель заказчика очень глумился над нами, например, у нас был испытательный стенд, и была клавиатура подключённая к испытуемому вычислительному комплексу, клавиатура испытующего компа, клавиатура термокамеры и т.п. И в документации была фраза:Для продолжении работы нажать любую клавишу.
Приходил представитель заказчика, читал это, нажимал клавишу Reset и уходил. И он был прав. И все такие неоднозначности были исправлены.
Nurked Автор
08.11.2021 16:54+2В мире есть две бесконечности. Вселенная и человеческая глупость. И я не уверен насчёт первой.
А на самом деле, если пользователь не понимает, что происходит, то винить надо разработчика.
beerchaser
08.11.2021 23:14+13Чисто технически Reset не клавиша, а кнопка. Таким образом от вас безнаказанно уходил пользователь, который злостно нарушил инструкцию.
Newbilius
09.11.2021 11:21+10Если в инструкции нет терминологии (описания чёткого отличие "клавиши" от "кнопки"), то пользователь в своём праве — в разговорном языке это синонимы. Не зря ведь есть RFC с определениями слов "must", "should", "may" и т.п.
beerchaser
09.11.2021 12:01+4Попросим автора выложить техническую документацию и сводную ведомость проекта? :) 99.99% что устройство "клавиша" в цепи формирования сигнала reset отсутствует)))
Ассоциативно: клавиша Sleep, расположенная на месте клавиши Delete на одной из клавиатур уже не помню какого производителя, доставила мне массу схожих ощущений. Особенно с учетом того, что из спящего режима машинка корректно не выходила...)))
dlinyj
09.11.2021 12:44+3Попросим автора выложить техническую документацию и сводную ведомость проекта? :)
Боюсь, что даже если бы у меня был к ней доступ сегодня, это попало бы под разглашение. Так что просто поверьте мне на слово. Но в целом, мне тоже не ясна разница между кнопкой и клавишей. И я не уврен, что там не была фраза: нажмите любую кнопку).
vesper-bot
09.11.2021 13:29+3Вообще, в далеком 1992м в ДНТТМ мне попадались клавиатуры с резетом во внешних окрестностях клавиши Esc — ой мы мелкие намаялись с ними!.. И не сказать ведь, что это была "не клавиша", там просто вариант PC AT такой был, с вынесенным резетом на клавиатуру.
drWhy
09.11.2021 13:57+5Искра-1030, например — Reset — красная кнопка в левом верхнем углу клавиатуры.
С породистым разъёмом РШ2Н с фиксатором на розетке и посеребрёными контактами.
vesper-bot
09.11.2021 14:02+1Очень похоже, кстати. Во всяком случае, F1-F10 были точно слева от блока с буквами в блоке 2х5 кнопок.
netch80
09.11.2021 19:01+3> С породистым разъёмом РШ2Н с фиксатором на розетке и посеребрёными контактами.
Оффтопик, но после «породистого разъёма» на автомате прочлось «посеребрёнными копытами». Пришлось затормозить и вчитаться.
> Искра-1030, например — Reset — красная кнопка в левом верхнем углу клавиатуры.
Зато вокруг неё рамочка была, чтобы не нажималась совсем уж просто так.
А на Агатах надо было нажимать пару СБР+УПР, поодиночке не работало.drWhy
10.11.2021 10:35+2Тут на выбор — «Серебряное копытце» Бажова, или «Золотая Антилопа».
Главное — не жадничать.
Osnovjansky
09.11.2021 21:03+4Что-то подобное попадалось когда-то в руки. Первое что нашел:
Turbo Plus KB-8001 R+ PS/2
Я уже и не помню, то-ли тогда удалось отключить кнопки Power и Sleep, то-ли просто выкинул. Но логику китайца, который воткнул эти кнопки в такое место, я так и не понял.netch80
10.11.2021 12:34+2Китайцы вряд ли такие вещи тогда сами придумывали, им это всё глупые развлечения белых варваров. А вот у кого возникла такая фантазия в США — да, хотелось бы найти и слегка поучить разуму.
ifap
10.11.2021 19:30+1А вот у кого возникла такая фантазия в США — да, хотелось бы найти и слегка поучить разуму.
Гейтса и Ко многие хотят сжечь, в очередь, сукины дети, в очередь! (с)
MasyGreen
14.11.2021 18:40+1в конце концов я её плоскогубцами выломал. Новые клавы не покупали т.к. таких убогих закупили вроде ~2003
dlinyj
09.11.2021 11:21+5Где-то у меня остался телефон представителя заказчика, позвонить ему что ли и сказать, что 12 лет назад он был не прав и злостно нарушил инструкцию. Или всё же порадоваться, что он нам научил писать идеальные мануалы…
Vic_tor
11.11.2021 03:16+5Нам как-то демонстрировали какую-то разработанную для военных систему на ОС QNX. Основной упор делали на то, какая это устойчивая и надежная операционка. Черт меня дернул проверить как она реагирует на Ctrl-Alt-Del - система зависла так, что даже на Reset не реагировала, чего не должно быть в принципе. После передергивания питания, еще какие-то данные там у них слетели. В общем, о последствиях я долго старался не вспоминать.
drumminman
03.12.2021 12:30Есть клавиатуры с клавишами питания, спящего режима и перезагрузки. Так что может быть и клавишей. Другое дело, что они они неудобны обычно до ужаса.
iiwabor
08.11.2021 13:21+14Проблема того, что никто не хочет читать скучные длинные мануалы, сейчас усугубляется тем, что многие уже просто не могут это делать физически - мозг, привыкший к твиттеру и тик-току не может воспринять текст длиннее 150 символов и видео длиннее 30 сек.
Nurked Автор
08.11.2021 16:56+4О дааа!
Я так подозреваю, что все эти ваши проблемы с ADHD это миф. Они просто все заключаются в том, что с начала жизни желторотик ни разу не сел и не сделал ни одной вези от начала до конца. За один раз.
А жаль.
quillon45
08.11.2021 19:27+1А бывает, документацию читаешь-читаешь, а там косяк. Идёшь ажно на выбранную площадку для багрепортов, вдумчиво читаешь, находишь костыль.
А электронщикам ваще классно. Иди читай топик на форуме типа сахарка, о котором ты ещё узнать должен. Где-то.
Nalivai
09.11.2021 11:31+5Прошу вас, оставайтесь в своей области, не думайте что ваша компетенция в чем-то одном делает вас специалистом во всем, включая клиническую медицину.
Нет ничего хуже чем самоуверенный бумер уверенный что раз он мануал про докер прочитал, то и в диагностике нейрологических особенностей справится.
2PAE
08.11.2021 13:32+8Главное в инструкции понимание автора, что читать обязательно, а что нет.
Помню в какой то книге буквально в первом абзаце говорилось, что первая глава посвящена марксиско-ленинскому обоснованию вопроса.
Мне дико понравилось. И ведь не придерёшься. :)
The_Kf
08.11.2021 13:45+4что такое ICM Key. Инструкция об этом умалчивает. Думаете всё так просто, пойди и погугли? Ха, ага! Идите, попробуйте погуглите это, так, чисто по приколу. Вы увидите, что эта аббревиатура используется только инженерами NEC и никем другим. Нагуглить это будет невозможно. Просто нет никакого варианта найти эти данные в интернете. Надо будет звонить в техподдержку для инженеров, и общаться со специалистом. Если повезёт, Вам ответят.
http://www.valentinesystems.com/NEC_Cheat_Sheet.pdf - intercom key
mayorovp
08.11.2021 13:46+7Другой пример такого мануала — это документация по языку Rust. Об этом я уже писал. Первая глава полностью погружает читателя во все тяжкие языка. Но понять первую главу можно только изучив четвёртую…
Э-э-э, а что не так с документацией? Первая глава рассказывает как вообще установить компилятор Rust и как написать Hello, world. Предлагаете передвинуть эту информацию в конец книги?
inkelyad
08.11.2021 14:09+2Э-э-э, а что не так с документацией?
В том, что ее несколько видов. В данном случае ругаются на то, что в руки взяли не то, что надо было.
Nurked Автор
08.11.2021 16:58+4Как мы ржавели. История внедрения и обучения.
Сорри, я про эту статью говорил ????
Nurked Автор
08.11.2021 18:06+9Жесть! На хабре, оказывается, можно смайлы вставлять. Очень каюсь, это клавиатура на смартфоне автозамену сделала. Ребят, не убивайте. Я реально не хотел, а править коммент уже не могу 8-(
vesper-bot
09.11.2021 09:57+3А чего такого? Хабр UTF8 compatible, а у кого есть в шрифтах эмодзи, те могут их вставлять и читать. А вот автозамена на смайл — новомодная фича телефонных клава-аппов, на ПК такой ещё поставить надо суметь.
Nurked Автор
09.11.2021 09:58Да меня просто заминусовали нафиг. Ну серьёзно, где такое видано — смайлы в камментах?
Это прям как на реддите.
Mingun
08.11.2021 18:35+2Не понимаю, что вам не понравилось. Даже на момент ее написания нужно было быть альтернативно мыслящим, чтобы не понять, что там написано. Ну либо ярким представителем того самого поколения, не привыкшем читать мануалы.
Zoolander
09.11.2021 07:16+3если вы не понимаете, что не понравилось другому человеку - хотя бы на рациональном уровне, никто не требует истинной эмпатии - боюсь, разговаривать с вами бесполезно
я понимаю, что вам не понравилось. Что у людей нет телепатии и умения мгновенно осваивать новые термины.
Это не нравится и мне. И поверьте, большинству людей - тоже.Mingun
09.11.2021 12:13+1Мгновенно осваивать новые термины как раз пытался автор, предлагая начинать с осваивания времен жизни из 4-й главы книги. Куда уж новее. А руководство построено как раз логично:
- глава 1 — установка и как напечатать текст в консоль, как собрать приложение, как управлять зависимостями
- глава 2 — показываем, как выглядит типичная программа на rust, реализуя простенькое приложение, причем не в готовом виде, как пытается показать автор, а по шагам, начиная с пустого (точнее, стандартно сгенерированного
cargo) телаmain. Боюсь, если это непонятно, то тут нужны не навыки телепатии, а навыки чтения. Причем ничего страшного не будет, если эту главу пропустить - глава 3 — типичные концепции языка программирования — переменные, типы, ветвления, циклы, функции, комментарии — в общем, синтаксис
- глава 4 — новая фундаментальная концепция — времена жизни. Причем это первая глава, где они вообще упоминаются.
mihmig
08.11.2021 14:09+6Слышал такое мнение: софт разрабатывается быстро, мануалы "не поспевают", да и дорого переписывать каждый раз.
А вообще, сложная система должна просто объяснить пользователю "что не так".
Вот сегодня банк прислал СМС - "Авто платёж не исполнен по техническим причинам"
И ЧО? В чате онлайн-банка ИИ-недоделка, по 8-800- девочка-попугай, максимум примет претензию со сроком рассмотрения 30 дней.
Автопроизводители со мной конечно не согласятся, ведь я отнимаю у них хлеб с маслом.
splitfire
08.11.2021 21:32+12банк прислал СМС — «Авто платёж не исполнен по техническим причинам»
Везде натыкаюсь на такое. Особенно раздражает появившаяся последние несколько лет манера вебкодеров — «Упс! Что-то пошло не так» вместо сообщения об ошибке. Ну не скотство ли!? Что не так? Чего надо этому говноподелию, что не устраивает?Nurked Автор
08.11.2021 21:36Особенно это раздражает на реддите. Где всё падает безвозвратно и не хочет начинать работать после этого.
mortadella372
08.11.2021 22:04+5Так они и сами не знают, бэк вернул 500. Ща кубер рестартанет проблемный под, и продолжим..
Nurked Автор
08.11.2021 22:06+2Ну да и нахрена нам вообще писать хороший код? Гдавное чтобы отработал одиножды. А если чё, кубер может перестартовать всё что под руку подвернётся.
vsb
09.11.2021 08:18+3Ну увидите вы стектрейс с NullPointerException и что будете делать с этим?
А какой-нибудь SQLException и вовсе может выдать данные о БД, что само по себе не совсем хорошо.
Смысл этого сообщения в том, что на сервере баг. И тут от вас уже ничего не зависит. Если процесс администрирования и разработки поставлен нормально, то подробные логи будут записаны на сервере и разработчики будут извещены, вероятно этот баг исправят через некоторое время. Ну или никогда не исправят. Баги случаются, да. Себестоимость ПО падает, тестированию уделяется всё меньше времени, предполагаю, что и качество ПО в некоторых областях падает (хотя с другой стороны есть и факторы, увеличивающие качество ПО).
swapper9
09.11.2021 09:41+8Нет, дело не в этом. Стектрейс некорректно показывать на пользовательском уровне (ну и с точки зрения безопасности тоже неправильно). А вот когда ошибки можно обозначаются кодом (причем не рестовыми 400, 500, а внутренними кодами) и этот код юзер передаст в поддержку, будет проще решить его проблему (и возможно проблему неверно написанного кода). К сожалению делают так редко, т.к. видимо хотят как можно меньше информации показывать бедному юзеру, а то вдруг устанет.
Mingun
09.11.2021 12:20+1Самое главное, что по этим кодам потом можно гуглить, что случилось, а по безликому "Ой! Что-то пошло не так" хрен поймешь, что это. То ли уже исправлено и нужно обновится, то ли что-то новое, а может банально конфиг не в том месте лежит.
zuek
12.11.2021 10:42+1Я когда писал "личный кабинет клиента", общающийся с 1С через "web-сервисы", умышленно отключал расширенную информацию об ошибках на проде, т.к. там или все явки-пароли-схемы текстовым json'ом, либо чистая отсебятина. В итоге, была процедура "ErrorReport", которая при наличии константы "debug", вываливала "простыню критичных данных" в интерфейс, а если константу не находила, то слала письмо на support@domain.tld с этой "простынёй" и прочими идентификаторами сессии. Не думаю, что я являюсь первооткрывателем этого "велосипеда".
Nurked Автор
12.11.2021 10:48+1Тут вы, я бы сказал, правы. Но, зависит всё от того, что вы покажете пользователю.
Ошибка соединения, невозможно подключиться к базе данных. Пожалуйста, обратитесь в техподдержу и скажите им 1226173. Это круто.
Упс. Всё упало. Мы чиним. Это не круто.
1A1A1
09.11.2021 10:08+1Ха! Сам писал такое в простеньком скрипте, потому-что отлавливать все типы ошибок для него превращало две строчки в 22.
Mike-M
09.11.2021 13:24+3софт разрабатывается быстро, мануалы «не поспевают», да и дорого переписывать каждый раз.
Да, «не поспевают». Да, переписывать дорого.
Но ни то ни другое не означает, что можно «забить» на документацию, я считаю.
lorc
09.11.2021 16:27+4софт разрабатывается быстро, мануалы "не поспевают"
Делаешь коммит меняющий внешнее поведение — сразу же обновляешь документацию. Иначе коммит не принимается. Документация естественно должна лежать в том же репозитории.
Я сейчас стараюсь придерживаться такого подхода. Он же принят в большинстве open source проектов (по крайней мере, тех, с которыми я работаю).
Kanut
09.11.2021 16:59+2Вот только очень часто изменения делают одни люди, а документацию для клиента пишут другие. Бывает что этим вообще занимается другой отдел или даже другая фирма.
lorc
09.11.2021 20:05+1Ну да, в моем случае это проще, потому что в большинстве своем это техническая документация - API или какие-нибудь опции командной строки.
А с другой стороны - чем занят отдельный человек или отдел пока программисты пишут код?
Kanut
09.11.2021 20:06+1Пишут документацию для продуктов других программистов.
lorc
09.11.2021 20:58+1Ну если они не успевают писать документацию для всех продуктов, значит нужно либо уменьшить количество документации, либо расширить отдел.
Правда, это мы уже уходит в сторону теоретического менеджмента...
Kanut
10.11.2021 10:29+4Это всё понятно. Да и ситуации разные бывают. Переводы на другие языки например. Или необходимость проверки документации с различных точек зрения, теми же юристами.
В изначальном моём комментарии речь шла о том что далеко не всегда удастся "привязать" документацию к коммитам. Особенно если речь об официальной документации.
drWhy
10.11.2021 10:45+1Любопытно, а после перевода продуктной документации на юридический язык она не растекается мыслью по древу, как пользовательское соглашение? Всё же это технический документ.
Kanut
10.11.2021 10:51+3Ну я одно время работал на фирму, которая делала "налоговый" софт. И там документация(да и вообще все формулировки, даже текст на кнопках) на "юридический" не переводились, но юристами проверялись.
Потому что если пользователь что-то понял неправильно и в результате неправильно подал декларацию(или вообще её официально не подал, а скажем вместо этого только сохранил как временную версию на серверах налоговой), то в теории фирму за это могли привлечь к ответственности.
perfect_genius
09.11.2021 18:32+1Почему бы это не автоматизировать, например, невозможностью оставить комментарий в коде и предложение в документации без привязки их к конкретному месту кода? И если этот код меняется — система сразу предупредит, что надо проверить связанный комментарий или документацию.
netch80
09.11.2021 19:04+2Автоматизировать невозможно, потому что связь может быть ну очень косвенная.
Newm
08.11.2021 15:45+8Больше всего "люблю" мануалы, в которых написано вообще НЕПРАВИЛЬНО.
Собирал по инструкции кровать для ребенка. Там под ней ящик. Собираю как написано в инструкции и понимаю, что чтобы произвести одну операцию (вроде бы вставить нижнюю картонку) необходимо 6 (ШЕСТЬ) рук. Вторую пару могла обеспечить жена, а вот от годовалого ребенка ничего путного добиться не удалось.
Лезем на ютуб и выясняем, что последовательность сборки ПРИНЦИПИАЛЬНО другая. Она намного быстрее и собирается он двумя руками, а проблем вообще не возникает.
Nurked Автор
08.11.2021 17:02+2Такими мануалами черти в аду топят костёр с бывшим персоналом телемаркетинга.
kharlashkin
09.11.2021 09:55+2Сталкивался с похожей проблемой у производителя мебели BRW - в комплекте не руководство по сбору мебели, а что-то типо отображения всех компонентов и место в общем изделии (может кто подскажет как это называется). А вот на оф.сайте уже можно было выкачать правильное руководство, где по шагам с картинками расписан порядок сборки.
Kanut
08.11.2021 15:59Я тяжело вздохнул, открыл бардачок, и, к ужасу парнишки, извлёк из него потрёпанный мануал 2004 года выпуска. После 20 секунд листания оного мануала, я ткнул пальцем в ту самую иконку, которая показывает, с какой стороны у тебя бензобак.
To есть по вашему "20 секунд листать мануал" это более удобное и правильное решение по сравнению с "за одну секунду глянуть на стрелку на приборной панели"? :)
Давайте посмотрим, что Вам можно посоветовать, чтобы люди от них вообще избавились.
Если можно сделать так что управление будет настолько интутивное что любой обойдётся без мануала, то что в этом плохого? На мой взгляд надо наоборот к этому стремиться.
aik
08.11.2021 16:29+12Нет. Правильно прочитать мануал и узнать о той стрелке из него, а не из случайного видео на ютубе
Kanut
08.11.2021 16:36+2Ну даже если смотреть с этой позиции, то почему одно более правильно чем другое? Или ещё какой-то третий вариант? То есть я могу понять "удобно" или "привычно". Но почему "правильно" или "не правильно"?
П.С. И я вообще не помню откуда я получил эту информацию про "стрелочку". По моему просто увидел когда машина показывала что бак пустой и было понятно о чём речь. Но точно не из мануала или видео :)
SergeyMax
08.11.2021 17:03+6Правильно прочитать мануал и узнать о той стрелке из него, а не из случайного видео на ютубе
Эта стрелочка - не более, чем забавный факт из серии "оргазм свиньи длится 30 минут". В реальности на первой же заправке после покупки авто вы запомните, с какой стороны у вас лючок бензобака, и далее не будете возвращаться к этому вопросу чуть менее чем никогда. Безо всяких мануалов.
Kanut
08.11.2021 17:09+3Так прикол этой стрелочки в том что она есть в куче марок. И если брать относительно новые модели, то чуть ли не у всех. То есть в основном от неё польза если едешь не в своей машине. По крайней мере для меня.
SergeyMax
08.11.2021 17:15+1Аа, тогда может быть. Мне просто не доводилось ездить не на своей машине)
Wesha
09.11.2021 00:16+4Эта стрелочка очень помогает в развитых странах — скажем, в США. Прилетаешь в командировку в какой-нибудь город, первым делом в аэропорту идёшь в фирму проката автомобилей, благо у выхода из аэропорта их штук несколько. А какие модели машин у этой конкретной фирмы — неизвестно, и, соответственно, где бак, тоже неизвестно. А со стрелочкой — сел за руль и сразу знаешь, какой стороной к бензоколонке вставать.
zuek
12.11.2021 11:46+1Задался вопросом, как выглядит символ "заправь меня" на УАЗ Патриот - у него лючки и горловины бензобака с двух сторон...
mortadella372
08.11.2021 20:21+2Более того. Шланг дотягивается до "другого" борта. Поэтому вообще пофиг.
vtal007
09.11.2021 09:41+1После смены авто по привычке подъезжал другим бортом. Стрелочки? да когда одна машина одна, то осмотря ее снаружи можно понять где находится лючек и без стрелочек
Но мануал к новому авто честно прочитал
Wesha
09.11.2021 23:07+2Правая рука тоже отлично дотягичвается до левого уха. Но большинство чешет всё же левой.
Neusser
10.11.2021 12:28+2Будет занята левая, почешете и правой. Так же как и с бензоколонкой, которая с нужной стороны бывает занята. И те, кто не знает, что можно подъехоть и другой стороной, стоят и ждут в очереди. Люблю таких - подъезжаешь к свободной мимо всех.
А бывает вообще цирк - однажды прямо передо мной какая-то девица разворачивалась в несколько приемов прямо у колонок, чтобы подъехать к шлангу нужной стороной. В итоге встала прямо между колонками и заблокировала свой то ли корсой, то ли микрой четыре штуки. Тоже, видимо, тикток смотрела.
konst90
09.11.2021 10:28+3На каршеринговой машине тоже предлагаете читать весь мануал перед началом поездки? Эти "лайфхаки из Тиктока" - не единственный способ получения некоторой информации, а лишь один из них. Что плохого в том, что молодой человек семнадцати лет узнает о стрелочке на панели из Тиктока и к моменту обучения в автошколе уже будет это знать без мануала?
Nurked Автор
09.11.2021 10:31Так я о том же и говорю, что мануалы превратились в ужас. А читать их стоит.
aik
09.11.2021 11:10+6Если это ваша первая машина, то мануал надо прочитать весь.
Машины всё же более-менее одинаковые и интерфейс имеют более-менее стандартный.
Узнавать же о том, что правая педаль — это тормоз, средняя — газ, а стрелочка показывает крышку бензобака из видео под названием «10 секретов вашего запорожца» — это неправильно.konst90
09.11.2021 15:24+1Эм, почему неправильно? Что плохого в том, что я узнаю о названиях педалей и смысле значков на панели не в автошколе, а раньше - лет в двенадцать, из Тиктока или книги "Что внутри автомобиля"?
Потом - почему вы уверены, что информация про стрелочки есть в мануале любой машины. Я вот сейчас открыл свой, на Калину - там про это ничего не сказано. Просто написано, что лючок находится с правой стороны авто, без привязки к значкам и стрелочкам. И на панели никаких стрелочек нет.
И да - справа газ, а не тормоз. А средней педали может не быть вообще.
BigBeaver
09.11.2021 15:23+3читать весь мануал перед началом поездки?
То ли дело посмотреть все тиктоки перед началом поездки…
netch80
09.11.2021 19:10+2> На каршеринговой машине тоже предлагаете читать весь мануал перед началом поездки?
У меня много лет автомат, а в 19-м в поездке взяли на две недельки Hyundai с ручкой. Так я завестись не мог, пришлось человека из рентовки звать. Кто ж знал, что типовая манера — требовать выжимания сцепления, чтобы оно разрешило запустить стартёром…
вот тут мануал пригодился бы.
vvbob
10.11.2021 10:05+2После пяти лет на автомате, взял в прокат машину на механике (только такие оставались у отельного прокатчика, а искать на стороне лень было). Ездил вообще без проблем, оказалось что "руки все помнят", и когда и как переключаться даже задумываться не пришлось. Но вот с запуском двигателя несколько раз косячил, привычка просто запускать на паркинге, на механике приводила к попытке запуска на первой передаче.
И потом, когда сел за свою машину, с автоматом, первое время левая нога непроизвольно давила на площадку под ней, при запуске двигателя "сцепление" выжимала.
zuek
12.11.2021 11:53+2Мне пришлось чуть больнее - на светофоре как тормозить на механике? - левая нога до упора в пол, правая аккуратно нажимает тормоз... сел на шеринг, доехать до автосервиса, впервые автомат... подъезжаю к светофору... а левая педаль довольно широкая... благо, сзади никого не было - "эстренное торможение" метров за 30 до стоп-линии - довольно неприятный манёвр.
При этом я чётко знал, что еду не на механике, знал основные особенности управления, но "ноги помнят", будь они неладны!
vvbob
12.11.2021 12:38+1У меня похожее было в первый раз на автомате, только там машина была со стояночным тормозом по американскому образцу - в виде педальки на том месте где у механики сцепление.. несколько раз "выжимал сцепление", притом что тоже все прекрасно помнил и осознавал. Хорошо еще что все эти разы были на небольшой скорости и никого близко сзади не было.
В общем да, меняя машину на ту в которой трансмиссия непривычна, стоит немного где-то покататься в безопасном месте, привыкнуть к управлению.
Nurked Автор
08.11.2021 17:04Да. Именно.
Для понимания чего либо, надо это "что либо" знать. А для знания этого тебе надо либо прочитать хороший мануал, либо быть создателем этой штуки.
sshikov
08.11.2021 17:41+2>На мой взгляд надо наоборот к этому стремиться.
Это стоит денег. Впрочем, как и написание мануалов (особенно хороших).Nurked Автор
08.11.2021 17:44Да тут такое дело, всё стоит денег. Только не стоит по этому поводу расстраиваться. Их, таки, можно заработать.
sshikov
08.11.2021 17:51+1Ну да. Или потратить, чтобы потом заработать. Тут скорее вопрос, что будет эффективнее, таки написать хороший мануал, или сделать нечто, чем можно пользоваться без мануала? Или наоборот, пусть звонят в поддержку, да еще и за деньги?
Я склоняюсь к тому, что бывает и так, и сяк. Например, можно ли пользоваться ноутбуком без мануала? С одной стороны, вроде бы да, а с другой, вот меня ребенок просит: «Папа, поставь мне еще один диск в ноут». И куда я тут денусь без мануала, если ребенок на даче, и я не могу взять отвертку, и открыть крышку? Более того, тут возникает интересный вопрос поиска этого самого мануала, при условии, что я не помню точно, какой модели ноут, и можно ли туда воткнуть еще диск, а если да, то какой, 2.5 или m2?
При этом скажем принтеры уже умудряются показывать на своем мелком экранчике инструкцию по замене картриджа или устранению замятия бумаги — то есть, там какой-то мануал уже внутри зашит.Nurked Автор
08.11.2021 18:04+3К сожалению, я думаю, что это "заболевание" современного мира. Мы решили, что мы не будем ничему учиться. Просто вот так вот взяли и забили. И не можем от этого теперь избавится. В своё время считалось, что если ты — мастер своего дела, то это потому что ты учился и тренировался годами. А сейчас эта учёба и тренировка сводятся на ноль.
Вот, например, у меня в кармане телефон с процессором Snapdragon 888. Мне, смертному, даже не предлагался мануал к этому телефону. Ни тебе информации о том, как его заряжать, ни тебе данных о том, как работает интерфейс.
И казалось бы, чего уж там, сам разберёшься. Как ткнуть зарядку в порт всякий знает. Как свайпать пальцами - выяснишь.
И вот при таком подходе начинает плодиться невежество. А я это невежество на дух не переношу. Потому что из него появляется магия, чудеса и охота за ведьмами. Теперь у нас есть куча тикктоков с рассказами о том, что надо свайпнуть слева направо и по спирали, чтобы вызвать определённые функции.
Человек перестаёт понимать то, что он создал. И начинает превращать это во что-то непостижимое. Нам, смертным, всем рассказали, что понять телефонную плату невозможно. Она слишком сложна для понимания, посему и понимать её не надо.
А через 50 лет вы найдёте эти телефоны, как мечи из валерийской стали. Их создала древняя цивилизация и никто не знает, как их создавать.
Другой, более реальный пример: когда я был маленьким я всегда знал, что соль бывает йодированной. Моя мама, доктор по профессии, объяснила, что это сделано для того, чтобы у меня не было заболеваний щитовидной железы.
А сейчас в США, например, бардак и хаос - народ в погоне за non-MSG, gluten-free и тому подобной, простите, хернёй, решил убрать йод из соли. Ибо это химикат.
Как вы думаете, кто-то читал статью о том, почему мы добавили йод в соль? Нет.
Результаты увидим через 50 лет.
sshikov
08.11.2021 19:08+6>К сожалению, я думаю, что это «заболевание» современного мира.
Ну, с одной стороны вроде да. Причем компаниям зачастую выгодно не учить пользователей, и не давать им мануалы — а то еще научатся батарейки в айфонах менять, чего доброго?
А с другой, я вижу каждый день на ютюбе просто «блоггеров», типа Игоря Негоды, которые способны завести без мануала турбину от МИ-8, и при этом ничего не взорвать и не поджечь. И они в тоже время не только мануалы читают, но и другие книжки, посложнее.
>Ибо это химикат.
Интересно, а они в курсе, что в соли еще и хлор есть?
На мой взгляд, наличие людей, которые верят в «соль без ГМО», не так важно. Такие люди были всегда, плюс-минус. Никакое образование пока не может этого изменить. Важно, чтобы эти люди не допускались к принятию решений за других. И важно самому таким не становиться.Nurked Автор
08.11.2021 19:14+1Важно, чтобы эти люди не допускались к принятию решений за других. И важно самому таким не становиться.
Плюс вам в карму за такие слова.
А с другой, я вижу каждый день на ютюбе просто «блоггеров», типа Игоря Негоды, которые способны завести без мануала турбину от МИ-8, и при этом ничего не взорвать и не поджечь. И они в тоже время не только мануалы читают, но и другие книжки, посложнее.
К сожалению, про Негоду ничего не знаю. Но, идею вашу понял. И, могу сказать, что это как раз, обратная сторона медали. С вами никогда такого не бывало?
Ваша девушка садится за компьютер, и пытается заказать какую-то цацку в интернетах. Через пять минут она смотрит на вас с расстроенным лицом и заявляет "Оно не работает".
Вы подходите к компьютеру, и чисто уже по привычке вытягиваете консоль в браузере, видите, что блокировщик рекламы ненароком убил ненужный скрипт, и чините всё за пару кликов. Да, в мануалах такого не напишут. Но вы же — программист. У вас достаточно знаний и вы сможете починить этот сайт, просто потому что вы прочитали не меньше 500 различных книг по программированию.
Exclipt
08.11.2021 23:34+1Предыдущий комментатор написал очень важные слова про то, что некоторые люди были всегда, и они не должны быть допущены к принятию решений. Все правильно, но самый цимус в том, что оно уже давно так и есть, и так будет. Просто 15 лет назад мы не были в курсе, что таких людей много, а прогресс дал им доступ в интернет. То, что мы увидели масштаб бедствия - это положительный момент, который позволит изменить жизнь к лучшему, а вывод "тиктоки породили толпы безмозглых" в корне не верен, тиктоки просто нашли свою аудиторию, тем и живут.
Nurked Автор
08.11.2021 23:37+1Хотелось бы верить, что вы правы.
В принципе — вы правы.
Но. Есть люди, которые считают, что если тиктоки популярны, значит они — сила.
Хрен с ними, с тиктоками. Сколько раз вы видели лбдей, которые вместо того, чтобы разбираться в доках к языку, копипастят стаковерфлоу?
Exclipt
09.11.2021 00:00+3Я сам копипасчу, но как я уже писал в комментариях к совершенной другой статье: с помощью ножа можно и салат сделать, и палец себе отрезать. Стековерфлоу - ровно такой же нож, из последних примеров - у ребенка 12-и лет на убунте не прошивалась ардуинка по поводу того, что "юсб порт траляляля", правильно конечно сесть да разобраться, но задача была заставить светодиод светиться здесь и сейчас, чтобы ребенок увидел результат своих трудов. Какое решение я выбрал, вы понимаете.
А то, что люди считают, что популярные тиктоки - сила, это тоже хорошо, даже дважды: вам теперь проще таких людей идентифицировать, и у вас в будущем будет меньше конкурентов.
Nurked Автор
09.11.2021 00:06+2Правду глаголите. Тут, для того чтобы это всё разрешить, нам нужно получить данные от пользователей стака.
Несомненно, я сам там решал вопросы. Например, когда компиляция рушило ядро. Это было страшно. Стак помогает.
Так что аналогия с ножом - 100%
VerdOrr
15.11.2021 01:56+1В истовом согласии с вашей точкой зрения далеко не сразу понял опечатку - мозг пытался просто переставить буквы...
ilyasok
08.11.2021 21:57Избыток не менее, а в наше время сытости, даже более вреден чем недостаток. По карте можно найти территории с избытком или недостатком йода в почве, и воде, соответственно.
Йод-ассоциированне болезни тоже имеют место ничуть не меньше. Человечество в процессе эволюции, когда была борьба за ресурсы всегда, неплохо научилось справляться с недостатком путем многкратного использования (вторичное усваивание в кишечнике, например), а вот с избытком - хуже. Ожирение, рак, диабет - все эти болезни избытка. И даже вирусы и бактери нуждаются прежде всего в питательной среде для размножения. И потому гораздо лучше живут в организме сытого.
Медицина переписывает свое мнение постоянно (не только программы и железо устаревают :-) ), нередко на диаметрально противоположное... Последнее из громкого - мнение по поводу насыщенных жиров в пище изменилось на 180 градусов в прошлом десятилетии.
Любая агрессивная борьба прежде всего приносит разрушение и вред. И не важно это борьба за или против чего-то. История полна примерами.
Exclipt
09.11.2021 00:06+3Вот прямо реально вирусы и бактерии "гораздо лучше живут в организме сытого", потому что там "жрачки много"? Особенно вирусы?
Я как-то всегда считал, что такая животинка живет лучше только там, где с ней хуже борются. А это точно не про голодных.
DevAdv
09.11.2021 03:41А сейчас в США, например, бардак и хаос — народ в погоне за non-MSG, gluten-free и тому подобной, простите, хернёй, решил убрать йод из соли. Ибо это химикат.
Можно ссылку на то, что "народ решил"? Интересно, потому что я о таком не слышал, хочу почитать аргументацию и в целом посмотреть кто против, кто за.
Wesha
09.11.2021 04:04Как вы думаете, кто-то читал статью о том, почему мы добавили йод в соль? Нет.
Утверждают, что вполне достаточно того йода, что потребляется с едой.
gorgona45
10.11.2021 19:14+1Утверждают, что вполне достаточно того йода, что потребляется с едой.
Интересно, почему же в Швейцарии до 20 века с йодом была проблема, и были очень распространеня заболевания щитовидки, характерные для его дефицита?
netch80
12.11.2021 14:38+1С едой — это потому что соль в еде уже йодируют, независимо от того, нужно это или нет. Поэтому дополнительное йодирование чаще всего не нужно. Но раньше этого не было. И в принципе это неправильно, не надо йодировать еду.
Недостаток йода характерен для горных районов, да (в Украине — Карпаты).
saege5b
08.11.2021 23:09+3Так на пятый год владения машиной, можно узнать про уличный/салонный термометр/гигрометр/барометр
Nurked Автор
08.11.2021 23:13+2Ага. Или вот, меня например добивают старые машины с невыставленными часами.
Mike-M
09.11.2021 13:36+1Бывает и наоборот, обнаруживаешь в машине функции, не описанные в руководстве.
Случайно заметил, что если удерживать рычаг стеклоочистителя в верхнем положении более одной секунды, то щетки начинают работать в два раза быстрее. В мануале об этом ни слова.
Это к вопросу о необходимости документации и её качестве.drWhy
09.11.2021 13:59О скромно умалчиваемом функционале многих китайских поделок можно узнать нечаянно, пролистывая руководство похожи изделий.
Lesatik
08.11.2021 18:02+5Страшно даже вообразить, насколько приятнее стало бы жить в нашем мире, если бы каждый человек, выполняющий свою работу, делал её с полным осознанием того, какова её цель. И того, что произведённый им продукт (будь то программный код, или сваренный кофе, или доставленный груз) будет использовать какой-то другой человек.
А если бы ещё каждый и выполнял свою работу компетентно, а не "ради галочки" в ожидании конца рабочего дня.
А если ещё и соблюдая технику безопасности... Да мы жили бы в раю.
Кстати, именно в таком порядке я бы и строила структуру мануалов. Когда уже понятно, зачем ты что-то делаешь или используешь, то рождается интерес, а что там, что там уже понажимать можно? :) И оттуда логически вытекает "а что будет, если оно сломается?"
И расшифровкой непонятных терминов по ходу текста, конечно же. Боже упаси заставлять человека лезть в гугл или оставаться некомпетентным, если он чего-то не понял.
Вашу статью бы каждому техническому писателю давать на близкий к тексту пересказ как тестовое задание перед устройством на работу.
fpir
09.11.2021 12:10-1Это вы хороший учебник описали, а не мануал. Мануал дрянной. Мануал должен быть разбит на главы и в каждой главе должна быть описана одна задача от возникновения оной до полного решения. Со словарём терминов, строго, в начале или конце. Учебники перечитывают 1 раз максимум, поэтому надо создать полную картину. К мануалам возвращаются постоянно(я надеюсь), и как только я прочитаю, что к "dect базе можно привязать трубку, вопрос "для чего?" будет рассмотрен в 7 главе настоящего руководства, а порядок действий в 114" а как отвязать вообще хз, и можно ли, тут же мануал полетит в корзину, а я полезу в гугл или 4pda.
Nubus
08.11.2021 19:52+9Это лечитса если давать первую версию мануала человеку с улицы и просить выполнить операцию. Или позовите менеджера и дайте ему по мануалу поработать.
Мне так пришлось создавать мануалы по тех процессам. Юзабельной становится только версия 1.3+
Ещё одно-нужно ВСЕГДА давать информацию как прекратить процесс перед сложной и опасной операцией. Навсегда запомню как учил друга кататься на велике. Он с горки летел в машину, я орал ТОРМОЗИ, а он орал Я НЕ ЗНАЮ КАК!
Nurked Автор
08.11.2021 20:16+5Вы правы. Ещё надо предупреждать о том, что "следующее действие нужно выполнить за 5 минут, иначе клей засохнет и всё сломается. Перед тем, как выполнять следующее действие, прочитайте мануал целиком, и выполняйте, только если готовы".
Я думаю это, и то что вы описали, это два отличных дополнения.
Bobovor
08.11.2021 20:00-1Слишком категорично.
Идеал это как раз когда вешью можно пользоваться без мануала ввиду ее интуитивности. Потом идет интерактивная справка и только затем мануал.
Мир не идеален и не каждую вещь можно сделать интуитивной. Мануал тут скорее костыль.
Факт в том, что мануал это самый дешевый способ. Он дешевле качественного UI и системы справок и подсказок. Но тут другая цена - время пользователя.
ddddroid1195
08.11.2021 21:42+3Написанные Вами слова — это Ваш аватар. Это Ваш виртуальный помощник, который заменяет Вас перед толпой, пытающейся достать Вас вопросами.
Это ваш дубль.
RiseOfDeath
09.11.2021 09:33+2Еще добавлю пару примеров:
1. Пишет сам разработчик, довольно хорошо знакомый со своим творчеством. В таком мануале очень часто опускаются моменты, которые кажутся разработчику очевидными (зачастую они опускаются неумышленно т.к. разработчику даже в голову не приходит что кто-то не знает что такое, например, вышеупомянутый «ICM Key»)
2. Пишущий инструкцию считает что читающий инструкцию идиот. Со всеми вытекающими, типа «Чтобы запустить программу сначала вставьте вилку питания компьютера в розетку». Соответственно чтобы получить нужное знание приходится прочитать 90% бесполезной и очевидной воды.
3. Инструкция в которой вообще не рассмотренны «отступления» в сторону, «нестандартные» ситуации, возможные ошибки (или рассмотренны но самые банальные их варианты). Как пример — почти любая инструкция к почти любому электронному устройству содержит в разделе траблшутинга пункт аля «Устройство не включается: убедитесь что кабель питания вставлен в разетку, убедитесь что у вас есть электричество,убедитесь что устройство действительно не включилось, обратитесь в сервис».vvbob
09.11.2021 10:21+3Как пример — почти любая инструкция к почти любому электронному устройству содержит в разделе траблшутинга пункт аля «Устройство не включается: убедитесь что кабель питания вставлен в разетку, убедитесь что у вас есть электричество,
убедитесь что устройство действительно не включилось, обратитесь в сервис».Работал еще в самом начале нулевых в поддержке 1С, так вот там таких "проблем с этой вашей программой" было огромное количество.
"У меня ничего не работает!!!!!" начинаешь разбираться - оказывается что либо комп выключен, либо монитор, либо клавиатуру выдернули из гнезда.. Люди часто очень жестко тупят, и поэтому такие пункты вполне оправданы. Правда вот проблема, эти тупящие обычно и инструкций в принципе не читают.
konst90
09.11.2021 10:36+3По 3 пункту вспомнил забавный случай - стиральная машина была подключена через пилот, и в какой-то момент перестала работать. Оказалось - пилот сломался: лампочка на нём горела, а напряжения в розетках не было, а я такого варианта не ожидал, для меня пилот с горящей лампочкой был априори с напряжением. Хорошо хоть мастер оказался опытнее меня и ещё по телефону предложил подключить в другую розетку или проверить эту.
Mike-M
09.11.2021 13:56Чтобы запустить программу сначала вставьте вилку питания компьютера в розетку
Звонит мне как-то матушка, и жалуется, что у неё перестал включаться телевизор.
Приезжаю и вижу: вилка валяется на полу за тумбой.
Оказалось, что накануне мама убиралась в квартире. Чтобы протереть пыль на тумбе, нужно было переместить телевизор, а для перемещения — отключить его от сети.
Отключить отключила, а подключить обратно забыла (возраст).
Так что лучше уж избыток информации, чем её недостаток.
JayK
09.11.2021 10:55+4Очень хорошая статья. Эргономика очень интересная наука. В том числе и в части написания мануалов. К сожалению есть проблемы:
Мануал может быть написан для галки, производитель сэкономил денег, нехай пользователи сами разбираются. Такой мануал неинтересен и бесполезен.
Мануал написан во исполнение каких-нибудь законов, там написано что вода мокрая, огонь горячий, а электричество опасное. Какой либо полезной информации там не содержится.
Мануал написан для идиотов, таких которые со справкой и с диагнозом, соответственно нормальный человек из его не сможет извлечь ничего.
Соответственно у одних людей нет желания читать мануалы, а у других их писать.
Еще бы я разделил на мануалы на предназначенные для широкого круга лиц, и предназначенные для узких специалистов. Пример последнего допустим вики.микротик.ком Мануал очень годный и полезный, но для юзера никак неприменимый. Одни из самых крутых мануалов для всех подряд, я видел на стенах в учебке. Там в лицах и фигурах было показано как применять разнообразные штуки для убиения себе подобных, и не убиться об них самому.
AlexeyK77
09.11.2021 13:25+2Есть один момент, с которым сталкиваюсь на практике постоянно.
Оказалось, что достсточно много лет назад в школах (во вском случае в Украине) отменили сочинение как таковое вообще. Есть только диктант и изложение. И молодежь просто не приучена в достаточной мере писать нормальные тесты, культура изложения мысли длинной страница-две ослабла.
Приходится тратить время, учить просто писать тексты, вычитывать их как учителю в школе, возвращать на переработку.
Ясное дело, что нельзя обощать на все и вся, но вот личный опыт мой такой.Nurked Автор
09.11.2021 13:39+1Полностью согласен. Убивать в людях умение сочинять — это ещё скажется.
Deepwarrior
15.11.2021 20:09что достсточно много лет назад в школах (во вском случае в Украине) отменили сочинение как таковое вообще.
В украинское ВНО(аналог ЕГЭ) сочинения до сих пор входят. Учитывая, что школы натаскивают на ВНО довольно серьезно, заявление об отмене сочинений выглядит сомнительно
jakushev
09.11.2021 14:29+2Посыл понятен, но вот с этим категорически не согласен:
Вот и попытайтесь добиться этой цели. Предложите Ваш мануал ничего не понимающему в этом вопросе человеку, и посмотрите, сможет ли он выполнить инструкции, которые Вы описали?
Как раз любая инструкция предполагает некий набор знаний, позволяющий понять написанное и выполнить последовательность действий. Вот пример со Схемой Электрической Принципиальной. Чтоб понять, что к чему, читающий должен иметь навык крепкого радиолюбителя или, минимум, быть выпускником радиоремонтного ПТУ. Например, профессор - лингвист будет смотреть в эту книгу, а видеть фигу. С автомобилем - тоже некорректный пример. Производитель ТС полагает, что клиент - минимум окончил автошколу и имеет минимальные навыки вождения, ему не надо объяснять, зачем нужен руль и педали. Да и органы управления, их расположение, основные пиктограммы - прописаны в нормативах. Конечно, производитель может поменять местами педали тормоза и газа, но это чудное (ударение на ваше усмотрение) ТС никогда не будет одобрено для использования на дорогах общего применения. По этому, по мимо основной инструкции прилагают небольшой плакат с расположением основных органов управления (не педали и руль, конечно, а замок зажигания, кнопки регулировки сидений, освещения, стеклоподъемников и т.д.) А в основной - уже детали. Как преодолевать водные препятствия, как буксировать, регламенты... Книга полезная, но без ее прочтения можно доехать от салона до дома.
Но вот первые листы талмуда, предупреждающие, чего нельзя делать с вещью, предполагаю, не из за недостатка мозга у технического писателя, а прописанные нормы, плюс судебные прецеденты, уже набившие оскомину: "Внимание! Пирожок горячий!"; "Животных в микроволновке не сушить!"; "Зубную щетку применять исключительно орально.".......
Nurked Автор
09.11.2021 14:32Ну, тут вы правы. Всё надо делать в пределах разумного.
Кстати. Я ожидаю, что если вы водите автосредство, то школу вы закончили.
jakushev
09.11.2021 14:58+1Да. Уже более 20 лет назад. Третьи права уже. Но вот недавно купил жене старенького "француза", типа "бизнес" на поучиться. Из салона приехал, конечно, но сразу скачал мануал и "камасутру", ибо никогда на таких не ездил. И если кресло отрегулировал без проблем, то где рычажок регулировки руля - пришлось глянуть. И про странное поведение указателя температуры масла... Французы, все таки, немного технические извращенцы.
Ну и в сфере разработки автомобильного FW, в общей сложности более 10 лет работал, так что про машины могу говорить, как человек по ту сторону автосалона.
icelord2
09.11.2021 14:47+2Самые офигенные мануалы - сервисные (ремонтные) мануалы на старые Honda (до 2010года) там даже человеку ничего не понимающему в машинах разжёвано, крайне понято, что и как открутить, что и как померить в случае какой либо поломки, плюс иллюстрации ПОНЯТНЫЕ и легко читаемые. (если кому интересно могу скинуть пример, на любую Honda с 1982 по 2010 года выпуска)
drWhy
09.11.2021 15:58+4Наверно и у Кадиллака тоже были информативные мануалы — если помните в фильме «Близнецы» герой Шварценеггера, пролиставший мануал чтобы научиться водить автомобиль, поднимает его сзади для отключения сигнализации — автомобиль считает, что его поднимает эвакуатор и не бузит.
SignallerK
09.11.2021 20:06+1Мануал не только писать уметь надо. Им еще и пользоваться грамотно надо :) :
Deepwarrior
15.11.2021 20:23Или вот. Возьмите любой мануал к Вашему автомобилю. Там тоже можно повеселиться. Для начала Вам приходится читать о том, как правильно устанавливать ремни безопасности для транспортировки младенцев. Несомненно, родителям малышей эта информация очень полезна, но это не 100% всей аудитории. Что самое главное в машине? Она должна ездить. Информация о том, как сделать так, чтобы она поехала, начинается примерно после 120 страниц информации о том, как она ломается и как её не нужно обслуживать.
Мне хочется использовать мануалы для решения своих проблем. Да, прочитать целиком можно, но большая часть текста окажется ненужной прямо сейчас.
Потому мне наоборот хочется, чтоб вся необходимая информация была до начала необратимых действий, этого самого «ездить» у автомобиля. Потому что решив проблему «как ездить», и сразу попробовав, пока не забылось, о проблеме «как пристегнуть ребенка» можно и не узнать.
Javian
"Транзистория" же. :)
Nurked Автор
Ого. К сожалению не знаком. Пойду ознакамливаться.