Самая отстойная документация с которой вам приходилось работать

Вот это, к примеру - документация. А то, что в манах, это список ключиков с обрывочным описанием оных.

Файл по ссылке очень напоминает manual page. В чём хоть отличие то? Такое же описание ключиков. Или вы имеете ввиду что надо бы как то эти ключики организовать в группы а не писать их в алфавитном порядке? Тут соглашусь т.к. полнота документации от этого не пострадает а найти нужную информацию будет проще. Однако, уверяю вас man не худшая документация хотя и не лишена своих недостатков. Гораздо хуже когда написан туториал где показано как использовать пару ключиков к API, а остальное - ищите в бложиках разработчиков.

Windows Help. Если это считать документацией. После ЭТОГО - любая документация кажется идеальной.

При этом лучшей считаю документацию по Qt и по PHP.

Kwin 4.9 Scripting API http://techbase.kde.org/Development/Tutorials/KWin/Scripting/API_4.9

на первый взгляд — вроди ничего. Но посередине доки оформления почти нет, понимать сложно.

PyQt

Доки на GTK api

Хорошая дока у питона, ещё давно нашёл по jquery(с картой функций) на сайте jquery.page2pagе.

Ужасная дока у xlwt, в pdf. А вообще отсутствие злит больше всего.

Самое отстойное, это когда приходится работать с отсутствием документации...

только хотел это написать :)

В качестве мануала к плагину к одной проприертарной программе шёл полуторачасовой видеоурок с сильным шотландским акцентом. У нас ушло 13 месяцев (с июля прошлого года по август этого), чтобы понять, что у плагина не 2 режима работы, а 3, и 1 из них не работает. При том, что исходники были.

Самая лучшая документация - отечественная. Обычно всё разжёвываютдо мелочей. А самая плохая - на китайском.

Теперь открой какой-нибудь man tc, который (tc) по сложности на уровне или даже выше железки по моей ссылке, и сравни. Вот это - плохой ман, который я и имел в виду. Ну и для интереса, сравни с талмудами howto по тому же tc.

Самая отстойная документация - любые УП АТС, как советские M-200, Протон, так и всякие Siemens HiPath. Что документация, что управление станциями - кровькишки.

любые УП АТС, как советские M-200

Я тут привёл как раз эту документацию как недостижимо идеальную относительно линуксовых манов. Разжёвано всё, вплоть до протоколов.

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

Было дело как-то... делал драйвер для 2д ускорителя... Документацию с японского на английский переводили немцы.

у Протонов

может быть Протей? Там да, вырвиглазное нечитабельное нагромождение совок-стайл аббревиатур.

Программист с хорошим знанием техангла, способный внятно перевести свой язык на енгриш - большая редкость. Многие пишут на воробьином с примесями сленга и считают при этом, что они просто восхитительно здорово говорят на английском.

недопрограммисты не понимающие технический английский

Я довольно бегло говорю и могу написать статью, но если мне надо будет писать инструкцию - я отдам профпереводчику.

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

Многие пишут на воробьином с примесями сленга и считают при этом, что они просто восхитительно здорово говорят на английском.

Мне моего «игрового» инглиша вполне хватает, чтобы переписываться с румынскими разработчиками Yate, ибо они пишут примерно так же. :)

Хм.. Хороший man на мой взгляд. Может у вас в системе другой?

Я об этом и говорю. Потом такие китайцы, румыны и прочие не-носители языка творят документацию.

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

Ну давай ещё название функций, классов и т.д. на русском, цикл (переменная И = 0; И <= 25; И++),...

Уж лучше китайский английский, чем китайский китайский.

я вроде не говорил об этом

http://www.almaz-sss.ru/продукция/цатс-протон-ссс-серии-алмаз/

Как сейчас помню меня ставили в тупик такие вещи, как например:

Описание опции X в документации:

- для A - выставите опцию в A

- для B - выставите опцию в B

По факту в конфигурялке - нет ни A, ни B, но есть С,D,E

Причем в интернетах и специализированных телекоммуникационных справочниках не гуглится ни что за опция такая, ни, тем более, ни какие параметры у нее могут быть.

Вы кстати так и не перевели приведённую вами же выше фразу на русский. Интересно было бы узнать как звучит по русски. Прошу вас.

белка понятия не имеет как по-русски это сказать

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

// Draws rectangle at specified location with specified width and height,
// possibly filled with color
void drawRectangle(
  Point &location, Color &color, double width, double height, bool filled = false
) {
  // ...
}

Если в комментариях или документации будет по русски придётся по ходу дела ещё и переводить на лету что место расположения - это параметр location, цвет - это color, и т.д. Это лишний уровень сложности когда разбираешься и в без того сложном коде.

Кроме того, как уже говорилось выше, перевод документации получается либо состоящим на 70% из английских слов написанных русскими буквами либо не читаемым.

Поэтому русскому языку в программировании не место, пишите всё на одном языке - названия объектов программы, комментарии, документацию. Это намного удобнее, даже не нужно будет постоянно переключать раскладку клавиатуры.

Вот, вот, сами не знаете.

Ага. И абсолютно нечитаемый код, где документации в 10 раз больше, чем самого кода.

В Java каждый класс в отдельном файле. Никому же не мешают 18 строчек копирайтов в начале каждого файла. Заместо них можно краткий туториал.

almaz-sss

О нееееет, только не это. Эти товарищи сводили нас с ума, когда брали у нас телефонию. Клиент «подари врагу».

IBMовская дока по их недомейнфреймам.

iSida. Писал плагины к этому чуду. Чтобы получить что-то нормальное, пришлось копаться в ядре. С тех пор у меня фобия жаббер ботов на Python, ровно как и этого языка.

Хороший man на мой взгляд.

По голому «man tc» можно настроить нарезку скорости хотя бы на интерфейсе? Нельзя.

Можно если внимательно прочитать. Но вообще конечно вводный туториал из гугла не помешает.

Без туториала обойтись можно, а без man'а получится ощущение что ты не всё знаешь. По крайней мере у меня, люблю детально разобраться.

без man'а получится ощущение что ты не всё знаешь

/0

каким образом, если ман это чуть расширенный выхлоп ключика --help?

Man это наиболее полная документация которую я видел, подробнее можно познакомиться только путём чтения исходников который слава Столлмэну у нас есть.

Кроме того, тут речь не только о параметрах утилит, больше о документации к API библиотек где нет --help.

Согласен что зачастую туториал / howto бывает полезен. Но если к каждому случаю написан туториал из которого можно скопировать код зачем тогда программист? Copy/Paste сможет сделать и обезъяна.