Очень часто встречается просто графоманская. Да, она хуевая.
В ней вместо сути, очень академично(и с характерными миллионами тонн воды) описано всё, до мелочей. Но хуй тебе, а не пример. Продирайся через простыню текста на 30 страниц, хотя это можно было бы заменить тремя примерами с описанием в одну строчку, что в них что и зачем.
В ней вместо сути, очень академично(и с характерными миллионами тонн воды) описано всё, до мелочей. Но хуй тебе, а не пример. Продирайся через простыню текста на 30 страниц, хотя это можно было бы заменить тремя примерами с описанием в одну строчку, что в них что и зачем.
Нужно больше примеров! Наш мозг - это нейронка. И ее легче учить на примерах. Просто описать все не достаточно, т.к. собрать работающий вариант без примеров очень энергозатратно (больше времени и ментальных усилий потребуется)
Всё очень просто, вот есть ваш продукт, который решает какую-то задачу. Опишите подробно минимальный конфиг для того чтобы ваш продукт начал решать базовую задачу. Вот вам пример https://openvpn.net/community-resources/static-key-mini-howto/ , здесь подробно рассказывают как запустить самый простой шифрованный тунель, есть тонна и маленькая тележка статей и манов как настроить ОпенВПН, но 80% потребностей решается этой статьёй.
Грехи документации, с которыми я сталкивался:
1. Вода. Вместо того, чтоб написать лаконично и по делу, растекаются мыслью. Худшую документацию из всех виденных я сам лично писал в Intel вместе с техписателем. У техписателя очень своеобразное видение было. Описание функций библиотеки СТЕНОЙ ТЕКСТА вида: "вызовите функцию foobar, где аргумент hui это то, аргумент wtf это сё". Серьезно, даже прототип функции не приведен, просто текстом.
Если у тебя библиотека - пиши кодом + описание.
2. Отсутствие объяснения. Вот документация на стопицот функций, каждая что-то делает. Но как это использовать, какие концепции вложил автор в библиотеку - загадка.
Если у вас хоть немного сложная вещь, опишите, что это, почему, как, как это какие там охуенные упоротые идеи вложил разраб.
1. Вода. Вместо того, чтоб написать лаконично и по делу, растекаются мыслью. Худшую документацию из всех виденных я сам лично писал в Intel вместе с техписателем. У техписателя очень своеобразное видение было. Описание функций библиотеки СТЕНОЙ ТЕКСТА вида: "вызовите функцию foobar, где аргумент hui это то, аргумент wtf это сё". Серьезно, даже прототип функции не приведен, просто текстом.
Если у тебя библиотека - пиши кодом + описание.
2. Отсутствие объяснения. Вот документация на стопицот функций, каждая что-то делает. Но как это использовать, какие концепции вложил автор в библиотеку - загадка.
Если у вас хоть немного сложная вещь, опишите, что это, почему, как, как это какие там охуенные упоротые идеи вложил разраб.
Пытался у себя на работе это донести, но пока вбестолку, может, хоть тут меня поймут.
1. Документация должна быть ориентирована под читателя. Да, все люди разные, поэтому надо её разбивать на модули. Надо держать в голове что заинтересованный человек должен прочесть её от начала до конца -- если он будет пробегать глазами, обязательно упустит что-то важное. Многое из SOLID principles подходит и к документации.
Остальное можно найти в поисковике по documentation practices, но надо фильтровать. Вкратце: определить тип документа, подбор ключевых слов для поисковика, каждая страница может быть начальной, agile подход, документация по требованию.
1. Документация должна быть ориентирована под читателя. Да, все люди разные, поэтому надо её разбивать на модули. Надо держать в голове что заинтересованный человек должен прочесть её от начала до конца -- если он будет пробегать глазами, обязательно упустит что-то важное. Многое из SOLID principles подходит и к документации.
Остальное можно найти в поисковике по documentation practices, но надо фильтровать. Вкратце: определить тип документа, подбор ключевых слов для поисковика, каждая страница может быть начальной, agile подход, документация по требованию.
Я допустим читаю юзер-мануалы. Только там как правило всё сводится к тому, что "в случае возникновения ошибок обратитесь к системному администратору".
А мне, как системному администратору, к кому обратиться, если этот кусок индусского кода не работает как надо?
Суки.
А мне, как системному администратору, к кому обратиться, если этот кусок индусского кода не работает как надо?
Суки.
Даже AWS...
Да у них как раз самая уёбищная документация ИМХО. Какой-нибудь одиночка на гитзабе пишет лучше описания. Как выше писали, всё часто упирается в отсутствии примеров. Или у них любовь на словах объяснять. А самое пиздецовая ситуация когда находишь статейку где уже неплохое описание идёт и даже краткое, а потом просто добавьте эту конфиугацию. А конфигурация многоуровневый JSON и пидарасы не удосужилсь упомянуть куда именно вставлять. А что бы понять как этот JSON устроен надо потратить кучу времени читая запутанное описание с ветвлениями.
И венец пиздеца, это их ебучие SEOшники что постарались на славу так, что когда гуглишь что-то 1я страница это ссылки на маркетинговые брошурки, с описанием как всё офигенно и удобно.
Да у меня пичот. И да, я понимаю что в целом это мощная система и когда ты поймёшь, всё работает как заклинание (особенно если не трогать лишний раз после :D ). Но DX там это пиздец.
Да у них как раз самая уёбищная документация ИМХО. Какой-нибудь одиночка на гитзабе пишет лучше описания. Как выше писали, всё часто упирается в отсутствии примеров. Или у них любовь на словах объяснять. А самое пиздецовая ситуация когда находишь статейку где уже неплохое описание идёт и даже краткое, а потом просто добавьте эту конфиугацию. А конфигурация многоуровневый JSON и пидарасы не удосужилсь упомянуть куда именно вставлять. А что бы понять как этот JSON устроен надо потратить кучу времени читая запутанное описание с ветвлениями.
И венец пиздеца, это их ебучие SEOшники что постарались на славу так, что когда гуглишь что-то 1я страница это ссылки на маркетинговые брошурки, с описанием как всё офигенно и удобно.
Да у меня пичот. И да, я понимаю что в целом это мощная система и когда ты поймёшь, всё работает как заклинание (особенно если не трогать лишний раз после :D ). Но DX там это пиздец.
Документалка магнитоле в авто Хёндай.
Кнопки подписаны сокращениями типа АWT или там SWF.
А в инстрункии так чёрным по белому написано, что кнопка AWT активирует AWT, а кнопка SWF активирует SWF.
А если у кого-то остались вопросы, то ой всё идите нахуй, обратитесь к диллеру
Кнопки подписаны сокращениями типа АWT или там SWF.
А в инстрункии так чёрным по белому написано, что кнопка AWT активирует AWT, а кнопка SWF активирует SWF.
А если у кого-то остались вопросы, то ой всё идите нахуй, обратитесь к диллеру
А в документации написано - "Не носите шлепанцы с носками". И что делать с этой "полезнейшей" информацией, когда задача стоит, и начальника не ебет, как ты ее сделаешь?
За последнее время довольно часто приходилось при получении тех или иных вещей лезть в документацию прям при старте, и в целом находил ответы на нужные вопросы. Но вот буквально сегодня прислали игрушку к которой сам Аллах велел приложить книгу "100500 ответов на вопросы для тупых и не очень", но там сука была тупо здоровенная картонка с тем как втыкнуть два кабеля. Причем там физически их не перепутаешь.
Чтобы написать коммент, необходимо залогиниться
Отличный комментарий!