М.Двач / Программирование

17 Кб, 178x259
Как писать хорошие документации 22 дек, 14:27 3610211 В конец треда | Веб

Хочу научиться писать понятные инструкции/документации/мануалы, ищу внезапные решения, может быть лучшие практики. Если что тред не ограничивается ЯП-ми, но кого если не программиста спрашивать как писать упорядоченные действия.

Вот некоторые советы, которые звучат как база:
- Тостировать свои инструкции, воссоздавая с нуля
- использовать рекурсивные уточнения
- представлять себя в роли человека, которому придётся читать
- заранее продумывать TL;DR и FAQ
- описывать только то, что есть (без загадывания)
- избыточность и уточнение очевидных пунктов
- не пропускать пункты, даже если они повторяются
- картинка > текста (Снег > текста)

Пишите свои дополнения к этому списку или просто хорошие практики.

Ответы672686678886684135700578704349

2 22 дек, 16:38 2 3610309

Нах самому писать, дух рождества с этим прекрасно справляется

3 23 дек, 12:32 3 3610843

Загугли MANUFACTURER’S GUIDE TO DEVELOPING CONSUMER PRODUCT INSTRUCTIONS

4 25 дек, 14:56 4 3612270

бамп

sage 5 25 дек, 15:15 5 3612280

Хуямп.

6 26 мар, 00:05 6 3672686

>>3610211 (OP)
Вообще теоретически мануалы не нужны, программа должна подсказывать как ей пользоваться в том числе и через ошибки, они должны генерироваться автоматически и быть понятны, типа как генерируются вещи в диабле та же и тут.

Мануалы линукса полное говно и писалиь для тех кому больше нехуй делать как тыкать рандомную прогу для тестов, на это может уйти несоизмеримо больше времени чем на освоение принципов работы такой программы под капотом, парадок протухших вонючих абстракций налицо.
Прагматично можно добавить в существующие мануалы табуляции или пробелы для ранжирования опций по частоте и или значимости использования, чтобы даже беглый взглят по мануалу позволял адекватно использовать прогу например:
mdadm
Первыми по отступам должны быть --assemble и --stop, чтобы ты мог запустить RAID и сразу остановить его. Тоесть должна быть семантическая связность и структура. А почти что все мануалы линукса семантическая каша и простыня подкатом и читать это говно а некоторое типа мануалов mpv вообще величиной с мануал gcc но его то хотябы легче использовать, а там попытались какбудто курсы монтажёра засунуть в этом проблема что некоторые мануалы содержат контекст выходящий далеко за пределы DevOpsa если у тебя программа по дизайну, ты что туда курс дизайнера засунуть собрался или нотную грамоту?
Поэтому сейчас особенно с использованием ИИ сталот понятно что мануалны это говно несущее исключительно юридический и справочный смысл но никак не мотивировочный, никто работу программ и тем более суть использования программы никогда не изучал по мануалам, суть продукта всегда лежит за пределами девопсинга, если ктото утверждает обратное можно плюнуть ему в ебало. Изучать тему по мануалам может только психически нездоровый, поэтому посыл читать мануал это равносильно только посылу нахуй и больше ничего. Те кто думают что читают чтото по мануалам на самом деле находятся в ницшеанской когнитивной ловушке: человек может прочитать только то что он уже и так знает, то что человек не знает он прочитать не в силах, это к самокритике тех кто думает что они чтото там читают по мануалам.
Алсо давно в относительно лохматые годы был у меня в шараге препод который заставлял работать вчерашних школоло задроченных до кретинизма сруsнявопидорской литературой исключительно в консоли. Ещё это престарелый долбаёб любил частенько раковать мемами из лурочки, в том числе RTFM прямо в аудитории. Вобщем все эти попытки послать читать мануалы не более чем попытка самоутвердиться и доминировать переадресовать агрессию на тех кто тебе ничего не сделал, в то время как ты нихуя не можешь сделать тем кто мокал тебя головой в унитаз.

6 26 мар, 00:05 6 3672686

>>3610211 (OP)

mdadm

Показать весь текст
Ответы672694672695672733673060

7 26 мар, 00:25 7 3672694

>>3672686
>и читать это говно
будет только психически больной аспергер какойнибудь с манией коллекционирования.

8 26 мар, 00:29 8 3672695

>>3672686
>Алсо давно в относительно лохматые годы был у меня в шараге препод который заставлял работать вчерашних школоло задроченных до кретинизма сруsнявопидорской литературой исключительно в консоли. Ещё это престарелый долбаёб любил частенько раковать мемами из лурочки, в том числе RTFM прямо в аудитории. Вобщем все эти попытки послать читать мануалы не более чем попытка самоутвердиться и доминировать переадресовать агрессию на тех кто тебе ничего не сделал, в то время как ты нихуя не можешь сделать тем кто мокал тебя головой в унитаз.
Это к слову о среднем психологическом портрете пидора вместо ответа на вопрос посылающего читать мануалы, это просто опущенное чмо которое обоссывали в детстве и оно думает что знания какой то там обоссанной простыни делает его особенным.

9 26 мар, 07:17 9 3672733

>>3672686
>человек может прочитать только то что он уже и так знает, то что человек не знает он прочитать не в силах
таблетки выпить не забудь

Ответы672904

10 26 мар, 12:05 10 3672904

>>3672733
Это была метафора, не твой уровень.
И распечатать свои мануалы на A4 не забуть петух.

11 26 мар, 14:22 11 3673060

>>3672686
>Ещё это престарелый долбаёб любил частенько раковать мемами из лурочки, в том числе RTFM прямо в аудитории.
RTFM это аналог женского "я всиго дабилась сама" от ЧСВшного пидора, которому посчастливилось в 90х втыкать за компом с интернетиком, а не хуй сосать за гаражами и по подъездам и это он почемуто считает своей заслугой, а не чужой.

Ответы677626

12 2 апр, 07:53 12 3677626

>>3673060
Чатикодебил, бесплатно бывает только чат, бессмысленная болтовня. А что-либо стоящее никто тебе с ложечки кормить не будет, халявы не бывает. Хочешь получить профиты, должен платить за обучение, или самообучайся RTFM. Няньки стоят денег, бесплатно никто тебя не будет няньчить, инфантильный ребенок, кроме твоей мамаши шлюхи, вот и обращайся к ней, требуй чтобы учила тебя просто так и обзывай ЧСВшной пидрилой если откажется.

Ответы677659678167

13 2 апр, 09:07 13 3677659

>>3677626
Ебать xoxлогной рвётся от упоминания документации. Не смогу осилить книжку по информатике за 8 класс, уебище?

14 2 апр, 22:20 14 3678167

>>3677626
>Чатикодебил, бесплатно бывает только чат, бессмысленная болтовня.
Напиши много бессмысленного, мне скучно.

>А что-либо стоящее никто
Лол считать стандартную юридическую портянку считать стоящей. Эти маны нахуй никому не упёрлись маня кроме выжимок и то если заранее знаешь что за выжимки.

>Хочешь получить профиты, должен платить за обучение, или самообучайся RTFM. Няньки стоят денег
Сначала заплати штраф за фейл обучалово в школаче.

>бесплатно никто тебя не будет няньчить, инфантильный ребенок
Так и хули ты ко мне припёрся хуесос недокормленный иди у себя отсоси, самостоятельный ты наш и самодостаточный.

Ответы678351

15 3 апр, 10:16 15 3678351

>>3678167
>Эти маны нахуй никому не упёрлись
Почему тогда у тебя сраку рвёт: кто-то должен за тебя их читать, а тебя сосочку потом с ложечки кормить? Не твоя нянечка мамаша шлюха, обращайся к своей, ей и расскажешь какая она ЧСВШная пидрила.

Ответы679314

16 3 апр, 19:18 16 3678886

>>3610211 (OP)
>свои дополнения
Побольше примеров использования

Ответы679314

17 4 апр, 16:42 17 3679314

>>3678351
Иди ты нахуй со своими "перфокартами для людей" говно ты ебаное. Маны это неюзабельное говно. Они должны быть встроены в отчёты по ошибкам, красиво отформатированы и повсякому встроены в интерактивщину, простыни можешь сам наворачивать если тебе делать нехуй.
Обучение всегда идёт через continues разработку и примеры >>3678886. Обучение должно быть интерактивным и событийно ассоциированным.
Почему например никто никогда не выучивал язык по книгам например? Потому что слова эмоционально не ассоциированы с реальным опытом так же и здесь можно конечно читать и учиться по мануалам наверное лет 30 назад но сейчас нахуй не нужно, слишком много всего время не резиновое.

Ответы680513

18 6 апр, 12:50 18 3680513

>>3679314
>кто-то ДОЛЖЕН для меня сосочку красиво оформлять, но не я
Никто тебе не должен кроме твоей мамаши шлюхи, вот к ней и обращайся, а другие люди не твои нянечки чтобы няньчить дитятко обоссаное. Хочешь чего-то от других, сначала делай это сам, читай маны, оформляй красиво САМ, ДЛЯ ДРУГИХ. А другим делать нехуй, чтобы заниматься этой ерундой, будут тебя хуесосить что ленишься им красиво сосчку не оформляешь. Съебал работать, читать маны, а мне некогда, слыш, животное? Работай, скот, ради меня.

Ответы680662

19 6 апр, 15:34 19 3680662

>>3680513
Сам жри свои перфокарты, дырка драная.
Причем пока не предоставишь видео пруфы, что ты всё это прочитал ебальник свой дырявый не раскрывай пиздабол и хуесос ты свинособачий.

С программированием вообще проблем никаких нет и не бывает, а с манодокументопростынепортянкоговном проблемы вообще всегда. И здесь нужно навести порядок в сторону политики human friendly.

И ты >>3680513 пидор будешь обязан соблюдать этот порядок.

Ответы681366

20 7 апр, 12:25 20 3681366

>>3680662
>будешь обязан соблюдать этот порядок
Ты уже обязан или сам себя исключаешь? Вот и я себя исключаю, а ТЫ обязан. Работай, скот, ради меня, ты мне обязан, делай мне удобно, мне самому ебаться с манами некогда, для этого есть ты.

Ответы683355

21 9 апр, 15:00 21 3683355

>>3681366
>Ты уже обязан или сам себя исключаешь?
Нехуй мне вопросы задавать хуйлятина тупорылая, тебя уведомили что тебе делать, завали свой ебальник и пиздуй переписывать маны на человекочитаемый вид, как это принято делать с кодом на языках программирования.
Исключить ты можешь себя вместе со своим высером недоманом олигофрен непонятливый. Либо делай качественно, либо не сри хуйнёй.

191 Кб, 1920x1080
22 9 апр, 15:47 22 3683415

Вот в качестве наглядного и короткого примера уёбищного сучьего мана это ман по chmod.
Нихуя не написано ни про биты соответствия ни про про стики биты, одна сплошняком насранная простыня говна. Под "написано" я монимаю то что можно бегло прочитать начав из рандомного места. А простынепидор - не человек.

23 9 апр, 15:59 23 3683428

Проблема в том что когда высирались эти маны люди ещё было в моде читать говнокниги от говнопейсателей и не было в обиходе слово семантика. Так вот эту самую семантику ман и должен отображать, и действовать именно как оботражение (семантики) прежде всего, а не содержать логику глубоко под сложносочинёнными предложениями ака СПП ССП и прочим говном.

24 10 апр, 12:43 24 3684135

>>3610211 (OP)
Устройся на работу в госшарагу, где при выполнении госзаказа правильно оформленные бумажки важнее, чем качество ПО.
Там-то тебя научат оформлять документацию по ГОСТ.

Ответы687222

25 15 апр, 11:46 25 3687222

>>3684135
>проекции какойто задроченной секретутки из ноунэйм канцелярии

26 6 мая, 01:39 26 3700578

>>3610211 (OP)
Основная проблема мануалоговна, что их авторы написавшие их для себя не понимают одной вещи: прочитать !=<<<<дохуя скобок>>>> понять прочитанное. Это проблема как минимум когнитивного разрыва, человек который пишет думает что пишет понятно.

>- использовать рекурсивные уточнения
This. Наглядность мануала вообще должна быть софрмирована отступами, где бы в идеале вообще всё было в виде 2мерного атласа где каждая опция сгруппирована и на своём месте, чтобы ткнув пальцем в любую точку можно было использовать программу с наскока как это происходит с библиотеками в программировании.

>- представлять себя в роли человека, которому придётся читать
Пидором гнойным не быть тоесть. Перевёл.

>- заранее продумывать TL;DR и FAQ
Группировать опции и юзкейсы по отступам в соответствии со статистической частотой использования и контекстной близостью.

>- описывать только то, что есть
> (без загадывания)
Это как?

>- избыточность и уточнение очевидных пунктов
Приведение примеров будет очень кстати.

>- не пропускать пункты, даже если они повторяются
Недооценённый пункт. Повторяющийся пункт выравнивать по отступу чтобы при уменьшении текста его сразу было видно в нескольких местах.

Ещё ОБЯЗАТЕЛЬНО должна быть референсность, мануалы должны ссылаться друг на друга образовывать группы и надргуппы и вообще вся инфраструктура и экосистема организована снизу вверх в виде DAG структуры мета атласа который тоже должен быть доступен в виде файла а сами мануалы тоже аналогичным образом были раскиданы по директориям, чтобы всегда было понятно что от чего зависит куда лезет и чем управляет, эти связи гораздо важнее какая то там буквоедская срань в каждой строчке на которую всем адекватам похуй.
Отсюда отход от юридичности мануала к его человекоориентированности.
Это восновном мануалов администрирования касается в первую очередь, в программировании таких проблем нет, ну ещё бы я блядь по каждой функции бы трактат читал блядь.
Только связи и только семантика, чтение подробноестей строго по желанию тем кому делать нехуй.

>- картинка > текста
> (Снег > текста)
Ты наверно имел ввиду снег текста < визуального контента, диаграм и прочего.
Это правда обоссанные портянки нахуй не нужны, и это можно считаь психическим расстройством - тяга перевести всё и зафиксировать в формать текста, какбудто до этого формулируемая логика отсутствует.

26 6 мая, 01:39 26 3700578

>>3610211 (OP)
Основная проблема мануалоговна, что их авторы написавшие их для себя не понимают одной вещи: прочитать !=<<<<дохуя скобок>>>> понять прочитанное. Это проблема как минимум когнитивного разрыва, человек который пишет думает что пишет понятно.

>- использовать рекурсивные уточнения
This. Наглядность мануала вообще должна быть софрмирована отступами, где бы в идеале вообще всё было в виде 2мерного атласа где каждая опция сгруппирована и на своём месте, чтобы ткнув пальцем в любую точку можно было использовать программу с наскока как это происходит с библиотеками в программировании.

>- представлять себя в роли человека, которому придётся читать
Пидором гнойным не быть тоесть. Перевёл.

>- заранее продумывать TL;DR и FAQ
Группировать опции и юзкейсы по отступам в соответствии со статистической частотой использования и контекстной близостью.

>- описывать только то, что есть
> (без загадывания)
Это как?

>- избыточность и уточнение очевидных пунктов
Приведение примеров будет очень кстати.

>- не пропускать пункты, даже если они повторяются
Недооценённый пункт. Повторяющийся пункт выравнивать по отступу чтобы при уменьшении текста его сразу было видно в нескольких местах.

Ещё ОБЯЗАТЕЛЬНО должна быть референсность, мануалы должны ссылаться друг на друга образовывать группы и надргуппы и вообще вся инфраструктура и экосистема организована снизу вверх в виде DAG структуры мета атласа который тоже должен быть доступен в виде файла а сами мануалы тоже аналогичным образом были раскиданы по директориям, чтобы всегда было понятно что от чего зависит куда лезет и чем управляет, эти связи гораздо важнее какая то там буквоедская срань в каждой строчке на которую всем адекватам похуй.
Отсюда отход от юридичности мануала к его человекоориентированности.
Это восновном мануалов администрирования касается в первую очередь, в программировании таких проблем нет, ну ещё бы я блядь по каждой функции бы трактат читал блядь.
Только связи и только семантика, чтение подробноестей строго по желанию тем кому делать нехуй.

>- картинка > текста
> (Снег > текста)
Ты наверно имел ввиду снег текста < визуального контента, диаграм и прочего.
Это правда обоссанные портянки нахуй не нужны, и это можно считаь психическим расстройством - тяга перевести всё и зафиксировать в формать текста, какбудто до этого формулируемая логика отсутствует.

Показать весь текст

27 11 мая, 20:38 27 3704349

>>3610211 (OP)
Программисты слишком заигрались в юристов в своём минигосударстве со своими законами и бюрократией любящими на фоне этого строчить целые ебучие правовые манифесты под каждой библиотекой, цена которым 3 копейки в базарный день.
Представье в программировании так к каждой переменной ебучая простыня текста. Это возможно результат некоторого влияния предствителей "самой читающей на планете нации".
Само запихивание сложной семантики в текстовый или строчной тип данных ущербно по своей сути.
Мануальщики вы ещё блядь дорожную карту в мануал блядь запихните. А потом говорите, что чтобы водить машину нужно читать мануал к дорогам. Ебало таких хуесосов представили?

28 14 мая, 16:50 28 3706145

Как понять мануал по ffmpeg или другому узкоспециализированному софту которое в использовании содержит сложную теорию в виде афинных преобразований хотябы? Ты это никак не поймёшь из петушиного текстика вот вообще. Теорию в мануал ты не засунешь, не говоря о том что даже простые программы требую накопления опыта использования, а текст всёравно нихуя не помогает.

Ответы706160

29 14 мая, 17:13 29 3706160

>>3706145
>афинных преобразований
>сложную теорию
Вскекнул

Ответы706382

30 15 мая, 08:10 30 3706382

>>3706160
Чего так? Это было приведено в качестве примера теории которую ты не засунешь в мануал, сложной для мануала тоесть. Я вотличие от мануалопидоров выражаюсь понятно.

Обновить тред
« /pr/В начало тредаВеб-версияНастройки/a//b//mu//s//vg/Все доски

Скачать тред только с превьюс превью и прикрепленными файлами

Второй вариант может долго скачиваться. Файлы будут только в живых или недавно утонувших тредах.Подробнее

Пользуетесь скринридером — пишите, что можно улучшить.
Host-Food.ru — надёжный хостинг от 12 руб/мес | Free DNS
Зеркала М.Двача: m2ch.hk, m2ch.lib, m2chfapiswfw2wcakptqp4o6ltgchvjuxfab7urxlduraomtlnhw5xad.onion