Trying random stuff for hours instead of reading the documentation / программирование :: Прикольные картинки :: funny pictures :: development :: programming :: engineering :: humor :: programming :: Юмор :: смешные картинки (фото приколы) :: разработка :: инженерия :: без перевода :: юмор (юмор в картинках) :: geek :: geek (Прикольные гаджеты. Научный, инженерный и айтишный юмор)

юмор без перевода инженерия программирование geek разработка смешные картинки humor programming Прикольные картинки 
Trying random stuff for hours instead of reading
the documentation,юмор,юмор в картинках,без перевода,инженерия,программирование,geek,Прикольные гаджеты. Научный, инженерный и  айтишный юмор,разработка,смешные картинки,фото
Подробнее
Trying random stuff for hours instead of reading the documentation
юмор,юмор в картинках,без перевода,инженерия,программирование,geek,Прикольные гаджеты. Научный, инженерный и айтишный юмор,разработка,смешные картинки,фото приколы,Юмор,programming,humor,engineering,programming,geek,development,funny pictures,Прикольные картинки
Еще на тему
Развернуть

Отличный комментарий!

Люди не читают документацию, потому что обычно она говняная. Неполная или непонятная. Даже на каких-нибудь крупных платных ресурсах, вроде AWS.
Mars53 Mars53 17.12.202219:31 ссылка
+34.5
Люди не читают документацию, потому что обычно она говняная. Неполная или непонятная. Даже на каких-нибудь крупных платных ресурсах, вроде AWS.
Mars53 Mars53 17.12.202219:31 ответить ссылка 34.5
Очень часто встречается просто графоманская. Да, она хуевая.
В ней вместо сути, очень академично(и с характерными миллионами тонн воды) описано всё, до мелочей. Но хуй тебе, а не пример. Продирайся через простыню текста на 30 страниц, хотя это можно было бы заменить тремя примерами с описанием в одну строчку, что в них что и зачем.
По работе занимаюсь формированием как технической документации для разработчиков, так и пользовательской документации. Можешь на примерах объяснить, в чем именно говяность документации, как на твой взгляд лучше / нужно и т.п.?)
Azaki Azaki 18.12.202201:00 ответить ссылка 0.0
Пишите кратко, емко и описательно. Тонны воды оставьте юротделу.
Ты не поверишь скольким людям нужно объяснять элементарные вещи. И насчет юротдела -- без определенной воды прилетит штраф на 100500 вечнозеленых, и таки заставят её внести.
Wolfdp Wolfdp 18.12.202202:21 ответить ссылка 1.0
Нужно больше примеров! Наш мозг - это нейронка. И ее легче учить на примерах. Просто описать все не достаточно, т.к. собрать работающий вариант без примеров очень энергозатратно (больше времени и ментальных усилий потребуется)
Всё очень просто, вот есть ваш продукт, который решает какую-то задачу. Опишите подробно минимальный конфиг для того чтобы ваш продукт начал решать базовую задачу. Вот вам пример https://openvpn.net/community-resources/static-key-mini-howto/ , здесь подробно рассказывают как запустить самый простой шифрованный тунель, есть тонна и маленькая тележка статей и манов как настроить ОпенВПН, но 80% потребностей решается этой статьёй.
Грехи документации, с которыми я сталкивался:

1. Вода. Вместо того, чтоб написать лаконично и по делу, растекаются мыслью. Худшую документацию из всех виденных я сам лично писал в Intel вместе с техписателем. У техписателя очень своеобразное видение было. Описание функций библиотеки СТЕНОЙ ТЕКСТА вида: "вызовите функцию foobar, где аргумент hui это то, аргумент wtf это сё". Серьезно, даже прототип функции не приведен, просто текстом.
Если у тебя библиотека - пиши кодом + описание.

2. Отсутствие объяснения. Вот документация на стопицот функций, каждая что-то делает. Но как это использовать, какие концепции вложил автор в библиотеку - загадка.
Если у вас хоть немного сложная вещь, опишите, что это, почему, как, как это какие там охуенные упоротые идеи вложил разраб.
Пытался у себя на работе это донести, но пока вбестолку, может, хоть тут меня поймут.
1. Документация должна быть ориентирована под читателя. Да, все люди разные, поэтому надо её разбивать на модули. Надо держать в голове что заинтересованный человек должен прочесть её от начала до конца -- если он будет пробегать глазами, обязательно упустит что-то важное. Многое из SOLID principles подходит и к документации.

Остальное можно найти в поисковике по documentation practices, но надо фильтровать. Вкратце: определить тип документа, подбор ключевых слов для поисковика, каждая страница может быть начальной, agile подход, документация по требованию.
Я своим на принципе колеса объясняю.
Плохая документация: колесо - круглый предмет, вращающийся на своей оси. (и нахера оно?)
Хорошая: примотав к колесу пару палок и медный таз, получим тачку, и сможем возить говно. (о! прям наша тема, берём!)
Я допустим читаю юзер-мануалы. Только там как правило всё сводится к тому, что "в случае возникновения ошибок обратитесь к системному администратору".
А мне, как системному администратору, к кому обратиться, если этот кусок индусского кода не работает как надо?
Суки.
Обратись к системному администратору, написано же.
Даже AWS...
Да у них как раз самая уёбищная документация ИМХО. Какой-нибудь одиночка на гитзабе пишет лучше описания. Как выше писали, всё часто упирается в отсутствии примеров. Или у них любовь на словах объяснять. А самое пиздецовая ситуация когда находишь статейку где уже неплохое описание идёт и даже краткое, а потом просто добавьте эту конфиугацию. А конфигурация многоуровневый JSON и пидарасы не удосужилсь упомянуть куда именно вставлять. А что бы понять как этот JSON устроен надо потратить кучу времени читая запутанное описание с ветвлениями.
И венец пиздеца, это их ебучие SEOшники что постарались на славу так, что когда гуглишь что-то 1я страница это ссылки на маркетинговые брошурки, с описанием как всё офигенно и удобно.
Да у меня пичот. И да, я понимаю что в целом это мощная система и когда ты поймёшь, всё работает как заклинание (особенно если не трогать лишний раз после :D ). Но DX там это пиздец.
Документалка магнитоле в авто Хёндай.
Кнопки подписаны сокращениями типа АWT или там SWF.
А в инстрункии так чёрным по белому написано, что кнопка AWT активирует AWT, а кнопка SWF активирует SWF.
А если у кого-то остались вопросы, то ой всё идите нахуй, обратитесь к диллеру
e-Blan e-Blan 18.12.202216:48 ответить ссылка 0.0
Сепульки
А в документации написано - "Не носите шлепанцы с носками". И что делать с этой "полезнейшей" информацией, когда задача стоит, и начальника не ебет, как ты ее сделаешь?
Так нормальные шлепанцы использовать надо, а не устаревшую хуйню без возможности подкинуть что-угодно куда-угодно.
Melatori Melatori 17.12.202219:41 ответить ссылка -2.3
Или будет мутное описание для чего нужны шлепанцы вообще и потом одно фото на ноге. Что делать, если у тебя носки, не написано.
Mars53 Mars53 17.12.202219:43 ответить ссылка 11.0
Или одна строчка - наденьте шлёпанцы (запустите сервер после установки) и никаких подробностей, никоманды, ни в каком порядке это делать, ни принципа запуска.
iHronos iHronos 17.12.202219:58 ответить ссылка 10.1
Всё по инструкции. Запускай в продакшн.
crkll crkll 18.12.202201:14 ответить ссылка 5.6
А может это ты, мудак, недоставил тегов? И вообще, как теги могут быть лишними, если они в тему?
18 + 18 + 17.12.202221:57 ответить ссылка 1.7
Ну дык это я и наставил) просто подумал что смищные картинки под тегом "программирование" будут лишними
забей
SEmp91 SEmp91 18.12.202203:25 ответить ссылка -0.4
Я настолько привык к авто-переводу картинок, что словил синий экран, когда увидел тег "без перевода" и текст на русском.
Zalmand Zalmand 17.12.202220:45 ответить ссылка -2.1
Что происходит на втором фрейме?
dialex-u dialex-u 18.12.202200:40 ответить ссылка 0.0
Тапок просунули через дырку в носке.
Retsu Retsu 18.12.202204:22 ответить ссылка 0.0
За последнее время довольно часто приходилось при получении тех или иных вещей лезть в документацию прям при старте, и в целом находил ответы на нужные вопросы. Но вот буквально сегодня прислали игрушку к которой сам Аллах велел приложить книгу "100500 ответов на вопросы для тупых и не очень", но там сука была тупо здоровенная картонка с тем как втыкнуть два кабеля. Причем там физически их не перепутаешь.
Wolfdp Wolfdp 18.12.202202:25 ответить ссылка 0.0
Но ты смог? Смог, да?
Старлинк?
ZGRLS ZGRLS 31.01.202322:48 ответить ссылка 0.9
Он самый.
Wolfdp Wolfdp 01.02.202300:32 ответить ссылка 0.0
Я не читаю ДК так как всё равно если случится поломка или что-угодно в пизду что там написано - не гарантийный случай. Или ебись с возвратами и т.д. Проще новое купить, а что подороже - не ломается( у меня)
Gorizont Gorizont 18.12.202203:26 ответить ссылка 0.0
А документация для портянок, потому что обновить забыли
Только зарегистрированные и активированные пользователи могут добавлять комментарии.
Похожие темы

Похожие посты
	Ш j	
		
BOOTCflMPS:
ANYONE WANN APPEND£5 GRAND OnÆ JAVASCRlÉHcbURSE!?.
____1Ш Newbie: So which programming language should I learn first?
Programmers: