Вот некоторые советы, которые звучат как база:
- Тостировать свои инструкции, воссоздавая с нуля
- использовать рекурсивные уточнения
- представлять себя в роли человека, которому придётся читать
- заранее продумывать TL;DR и FAQ
- описывать только то, что есть (без загадывания)
- избыточность и уточнение очевидных пунктов
- не пропускать пункты, даже если они повторяются
- картинка > текста (Снег > текста)
Пишите свои дополнения к этому списку или просто хорошие практики.
Вообще теоретически мануалы не нужны, программа должна подсказывать как ей пользоваться в том числе и через ошибки, они должны генерироваться автоматически и быть понятны, типа как генерируются вещи в диабле та же и тут.
Мануалы линукса полное говно и писалиь для тех кому больше нехуй делать как тыкать рандомную прогу для тестов, на это может уйти несоизмеримо больше времени чем на освоение принципов работы такой программы под капотом, парадок протухших вонючих абстракций налицо.
Прагматично можно добавить в существующие мануалы табуляции или пробелы для ранжирования опций по частоте и или значимости использования, чтобы даже беглый взглят по мануалу позволял адекватно использовать прогу например:
mdadm
Первыми по отступам должны быть --assemble и --stop, чтобы ты мог запустить RAID и сразу остановить его. Тоесть должна быть семантическая связность и структура. А почти что все мануалы линукса семантическая каша и простыня подкатом и читать это говно а некоторое типа мануалов mpv вообще величиной с мануал gcc но его то хотябы легче использовать, а там попытались какбудто курсы монтажёра засунуть в этом проблема что некоторые мануалы содержат контекст выходящий далеко за пределы DevOpsa если у тебя программа по дизайну, ты что туда курс дизайнера засунуть собрался или нотную грамоту?
Поэтому сейчас особенно с использованием ИИ сталот понятно что мануалны это говно несущее исключительно юридический и справочный смысл но никак не мотивировочный, никто работу программ и тем более суть использования программы никогда не изучал по мануалам, суть продукта всегда лежит за пределами девопсинга, если ктото утверждает обратное можно плюнуть ему в ебало. Изучать тему по мануалам может только психически нездоровый, поэтому посыл читать мануал это равносильно только посылу нахуй и больше ничего. Те кто думают что читают чтото по мануалам на самом деле находятся в ницшеанской когнитивной ловушке: человек может прочитать только то что он уже и так знает, то что человек не знает он прочитать не в силах, это к самокритике тех кто думает что они чтото там читают по мануалам.
Алсо давно в относительно лохматые годы был у меня в шараге препод который заставлял работать вчерашних школоло задроченных до кретинизма сруsнявопидорской литературой исключительно в консоли. Ещё это престарелый долбаёб любил частенько раковать мемами из лурочки, в том числе RTFM прямо в аудитории. Вобщем все эти попытки послать читать мануалы не более чем попытка самоутвердиться и доминировать переадресовать агрессию на тех кто тебе ничего не сделал, в то время как ты нихуя не можешь сделать тем кто мокал тебя головой в унитаз.
>и читать это говно
будет только психически больной аспергер какойнибудь с манией коллекционирования.
>Алсо давно в относительно лохматые годы был у меня в шараге препод который заставлял работать вчерашних школоло задроченных до кретинизма сруsнявопидорской литературой исключительно в консоли. Ещё это престарелый долбаёб любил частенько раковать мемами из лурочки, в том числе RTFM прямо в аудитории. Вобщем все эти попытки послать читать мануалы не более чем попытка самоутвердиться и доминировать переадресовать агрессию на тех кто тебе ничего не сделал, в то время как ты нихуя не можешь сделать тем кто мокал тебя головой в унитаз.
Это к слову о среднем психологическом портрете пидора вместо ответа на вопрос посылающего читать мануалы, это просто опущенное чмо которое обоссывали в детстве и оно думает что знания какой то там обоссанной простыни делает его особенным.
>человек может прочитать только то что он уже и так знает, то что человек не знает он прочитать не в силах
таблетки выпить не забудь
Это была метафора, не твой уровень.
И распечатать свои мануалы на A4 не забуть петух.
>Ещё это престарелый долбаёб любил частенько раковать мемами из лурочки, в том числе RTFM прямо в аудитории.
RTFM это аналог женского "я всиго дабилась сама" от ЧСВшного пидора, которому посчастливилось в 90х втыкать за компом с интернетиком, а не хуй сосать за гаражами и по подъездам и это он почемуто считает своей заслугой, а не чужой.
Чатикодебил, бесплатно бывает только чат, бессмысленная болтовня. А что-либо стоящее никто тебе с ложечки кормить не будет, халявы не бывает. Хочешь получить профиты, должен платить за обучение, или самообучайся RTFM. Няньки стоят денег, бесплатно никто тебя не будет няньчить, инфантильный ребенок, кроме твоей мамаши шлюхи, вот и обращайся к ней, требуй чтобы учила тебя просто так и обзывай ЧСВшной пидрилой если откажется.
Ебать xoxлогной рвётся от упоминания документации. Не смогу осилить книжку по информатике за 8 класс, уебище?
>Чатикодебил, бесплатно бывает только чат, бессмысленная болтовня.
Напиши много бессмысленного, мне скучно.
>А что-либо стоящее никто
Лол считать стандартную юридическую портянку считать стоящей. Эти маны нахуй никому не упёрлись маня кроме выжимок и то если заранее знаешь что за выжимки.
>Хочешь получить профиты, должен платить за обучение, или самообучайся RTFM. Няньки стоят денег
Сначала заплати штраф за фейл обучалово в школаче.
>бесплатно никто тебя не будет няньчить, инфантильный ребенок
Так и хули ты ко мне припёрся хуесос недокормленный иди у себя отсоси, самостоятельный ты наш и самодостаточный.
>Эти маны нахуй никому не упёрлись
Почему тогда у тебя сраку рвёт: кто-то должен за тебя их читать, а тебя сосочку потом с ложечки кормить? Не твоя нянечка мамаша шлюха, обращайся к своей, ей и расскажешь какая она ЧСВШная пидрила.
>свои дополнения
Побольше примеров использования
Иди ты нахуй со своими "перфокартами для людей" говно ты ебаное. Маны это неюзабельное говно. Они должны быть встроены в отчёты по ошибкам, красиво отформатированы и повсякому встроены в интерактивщину, простыни можешь сам наворачивать если тебе делать нехуй.
Обучение всегда идёт через continues разработку и примеры >>3678886. Обучение должно быть интерактивным и событийно ассоциированным.
Почему например никто никогда не выучивал язык по книгам например? Потому что слова эмоционально не ассоциированы с реальным опытом так же и здесь можно конечно читать и учиться по мануалам наверное лет 30 назад но сейчас нахуй не нужно, слишком много всего время не резиновое.
>кто-то ДОЛЖЕН для меня сосочку красиво оформлять, но не я
Никто тебе не должен кроме твоей мамаши шлюхи, вот к ней и обращайся, а другие люди не твои нянечки чтобы няньчить дитятко обоссаное. Хочешь чего-то от других, сначала делай это сам, читай маны, оформляй красиво САМ, ДЛЯ ДРУГИХ. А другим делать нехуй, чтобы заниматься этой ерундой, будут тебя хуесосить что ленишься им красиво сосчку не оформляешь. Съебал работать, читать маны, а мне некогда, слыш, животное? Работай, скот, ради меня.
Сам жри свои перфокарты, дырка драная.
Причем пока не предоставишь видео пруфы, что ты всё это прочитал ебальник свой дырявый не раскрывай пиздабол и хуесос ты свинособачий.
С программированием вообще проблем никаких нет и не бывает, а с манодокументопростынепортянкоговном проблемы вообще всегда. И здесь нужно навести порядок в сторону политики human friendly.
И ты >>3680513 пидор будешь обязан соблюдать этот порядок.
>будешь обязан соблюдать этот порядок
Ты уже обязан или сам себя исключаешь? Вот и я себя исключаю, а ТЫ обязан. Работай, скот, ради меня, ты мне обязан, делай мне удобно, мне самому ебаться с манами некогда, для этого есть ты.
>Ты уже обязан или сам себя исключаешь?
Нехуй мне вопросы задавать хуйлятина тупорылая, тебя уведомили что тебе делать, завали свой ебальник и пиздуй переписывать маны на человекочитаемый вид, как это принято делать с кодом на языках программирования.
Исключить ты можешь себя вместе со своим высером недоманом олигофрен непонятливый. Либо делай качественно, либо не сри хуйнёй.
Нихуя не написано ни про биты соответствия ни про про стики биты, одна сплошняком насранная простыня говна. Под "написано" я монимаю то что можно бегло прочитать начав из рандомного места. А простынепидор - не человек.
Устройся на работу в госшарагу, где при выполнении госзаказа правильно оформленные бумажки важнее, чем качество ПО.
Там-то тебя научат оформлять документацию по ГОСТ.
>проекции какойто задроченной секретутки из ноунэйм канцелярии
Основная проблема мануалоговна, что их авторы написавшие их для себя не понимают одной вещи: прочитать !=<<<<дохуя скобок>>>> понять прочитанное. Это проблема как минимум когнитивного разрыва, человек который пишет думает что пишет понятно.
>- использовать рекурсивные уточнения
This. Наглядность мануала вообще должна быть софрмирована отступами, где бы в идеале вообще всё было в виде 2мерного атласа где каждая опция сгруппирована и на своём месте, чтобы ткнув пальцем в любую точку можно было использовать программу с наскока как это происходит с библиотеками в программировании.
>- представлять себя в роли человека, которому придётся читать
Пидором гнойным не быть тоесть. Перевёл.
>- заранее продумывать TL;DR и FAQ
Группировать опции и юзкейсы по отступам в соответствии со статистической частотой использования и контекстной близостью.
>- описывать только то, что есть
> (без загадывания)
Это как?
>- избыточность и уточнение очевидных пунктов
Приведение примеров будет очень кстати.
>- не пропускать пункты, даже если они повторяются
Недооценённый пункт. Повторяющийся пункт выравнивать по отступу чтобы при уменьшении текста его сразу было видно в нескольких местах.
Ещё ОБЯЗАТЕЛЬНО должна быть референсность, мануалы должны ссылаться друг на друга образовывать группы и надргуппы и вообще вся инфраструктура и экосистема организована снизу вверх в виде DAG структуры мета атласа который тоже должен быть доступен в виде файла а сами мануалы тоже аналогичным образом были раскиданы по директориям, чтобы всегда было понятно что от чего зависит куда лезет и чем управляет, эти связи гораздо важнее какая то там буквоедская срань в каждой строчке на которую всем адекватам похуй.
Отсюда отход от юридичности мануала к его человекоориентированности.
Это восновном мануалов администрирования касается в первую очередь, в программировании таких проблем нет, ну ещё бы я блядь по каждой функции бы трактат читал блядь.
Только связи и только семантика, чтение подробноестей строго по желанию тем кому делать нехуй.
>- картинка > текста
> (Снег > текста)
Ты наверно имел ввиду снег текста < визуального контента, диаграм и прочего.
Это правда обоссанные портянки нахуй не нужны, и это можно считаь психическим расстройством - тяга перевести всё и зафиксировать в формать текста, какбудто до этого формулируемая логика отсутствует.