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

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

Самое отстойное - писать документацию по чужому корявому коду.

Самое отстойное - когда документация на китайском.

GTK, Ruby on Rails в ранние годы (сейчас говорят получше).

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

не скажи. Иногда проще взять дизассемблер, чем читать документацию.

... при постоянно меняющемся API.

Амдшная. Она вроде как есть но это какое-то крошево из регистров и их описаний

Давным-давно я пытался написать WM, так вот, документация по иксам — отстой. А лучшие доки — по Qt.

Да ладно. ТЫ еще манов на румынском не читал. В китайском - то все непонятно, а тут просто пипец, знакомые вроде слова, но смысл... Автопереводчики спотыкаются. Страшнее только маны на мове и болгарском. И польские, шифрующиеся под транслит.

И польские, шифрующиеся под транслит.

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

это какое-то крошево из регистров и их описаний

Приведи пример низкоуровневой документации к железу, которое не было бы крошевом из регистров и их описаний.

А у Интела многого нет. Даже в NDA-шной.

Самое отстойное писать документацию по продукту который даже не видел ...

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

Маны (которые по команде man) к любой мало-мальски серьёзной программе, да хоть к ip или iptables. Зачем ЭТО писать, если потом всё равно лезешь в гугл за howto/tutorial? Сразу в ман туториал вставляйте вместо этого кала.

Не помню уже названий, но вся документация к этим проектам состояла из доксидоки со скудными и бесполезными комментариями. Так и не понял зачем она вообще существовала.

По necessitas/андроиду доков чуть менее чем нет до сих пор.

Самый ад - это самописный полнофункциональный движок без документации совсем.

На какую - то прошивку, что ли, была документация из трех строк на английском и парастраниц на польском. Поляки делали, вроде для домашнего NAS. Или на chroot для нее, не помню. Суть в том, что ставилась она нетривиально, после прошивки ПЗУ надо было шить бутлоадер, загрузившись с диска, потом в чрут, экспорт из бута, дифф, патч, зашить и вообще ад. И все это на польском, много где вместо примеров - разъяснения. Я чуть не поседел, да, благо, уже лысина.

javadoc. Потому что обычно это выглядит как структура классов и полтора комментария. Зато разработчики могут с гордостью сказать «у нас есть документация».

Плюсую этого коментатора.

Руководство по работе с программами, написанными в Новосибирском ТФОМС. Оно пишется по мере написания программы в порядке включения фич, но не в месте добавления тех фич, а просто подряд.

А у Интела многого нет. Даже в NDA-шной.

Но так как NDA запрещает D, этого никто не знает.

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

Документация к телефонной станции Alcatel OmniPCX.

когда писал диплом, то пришлось перводить с японского, других языков не было у автора :/

олсо в убунтовских (и не только) репах есть пакет Ninix-aya, кто поймет как эту штуку заставить работать менее чем за 24 часа, тому надо идти в реверс-инженеры расшировщики. Когда-то я неделю убил на то, чтоб понять что к чему, с ковырянием исходного кода. В итоге запустил всё-таки интерактивного кота на рабочем столе. Щас уже не хватит терпения.

Маны (которые по команде man) к любой мало-мальски серьёзной программе, да хоть к ip или iptables. Зачем ЭТО писать, если потом всё равно лезешь в гугл за howto/tutorial? Сразу в ман туториал вставляйте вместо этого кала.

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

Понравились доки по кутям и пыху(пхп.нет). А самая ужасная документация -
это ее отсутствие.

Сайт rsyslog. Много воды и всякой ненужной инфы, и ни рожна не понятно как с этим rsyslog совладать.

Это если не знаешь что искать. Но согласен, примеры для самых распространенных юзкейсов в манах писать надо.

javadoc. Потому что обычно это выглядит как структура классов и полтора комментария. Зато разработчики могут с гордостью сказать «у нас есть документация».

javadoc само по себе не виновато. Если в javadoc комментах к каждому методу описать все возможные значения для его параметров, да ещё и пример использования получится отличная документация. Жаль что обычно никто этим не заморачивается.

Если в javadoc комментах к каждому методу описать все возможные значения для его параметров, да ещё и пример использования получится отличная документация

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

надо им написать, чтоб доки можно было писать методом @ref=$DOCDIR/foo/bar.html в комментарии. очень бы помогло в том же doxygene

Из открытых проектов, с которыми мне приходилось иметь дело, меня больше всего пробесила сгенеренная doxygen'ом документация в стиле капитана очевидности у ALSA.

RT5350_Preliminary_datasheet. Такого говна я ещё не видел.

потому что это и есть документация: детальное описание возможностей и функций.

А ты хочешь инструкцию к примерению/употреблению и варианты использования (это уже что-то более высшего порядка, т.е. производная от документации). Которая будет в разы короче и только совсем тривиальные вещи содержать

Ну так, ты думал всё просто так что ли раньше было?

Самое отстойное - писать документацию по чужой корявой реализации..

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

потому что это и есть документация: детальное описание возможностей и функций.

Перечисление ключиков утилит с обрывочным описанием это НЕ документация.

Мануалы к проприетарщине от каспера и русскоязычную мс-документацию. Очень много написано (или переведено) людьми, для которых русский язык явно не родной. Вообще похоже на отечественное законодательство, тоже без ПРОНИКНОВЕНИЯ ДУХОМ ЗАКОНА не разберешься.

Документация по госту на форматках а4, причём читать в строго определённых и сцуко неотапливаемых помещения. А потом понять что ничего нужного там небыло, и открытие темы получил просто так

Очень много написано (или переведено) людьми, для которых русский язык явно не родной

Именно что родной. Просто написано по стандартам профессиональных технических писателей: запрещается использовать сленг, никаких личных местоимений, сокращений и лирических отступлений, всё строго по правилам русского литературного со всей мощью его причастных и деепричастных оборотов.

Когда-то довелось читать соответствующую методичку со списком примеров как «надо» и как «не надо», и сразу стало ясно, что тех.писателем мне не быть.

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

Перечисление ключиков утилит с обрывочным описанием это НЕ документация.

Что же должна представлять документация как не описание всех возможных параметров и их значений? Если для каждого случая написать туториал думаю вам тоже трудновато будет найти нужный туториал. Пользуйтесь поиском. И мозгом.

Именно что родной. Просто написано по стандартам профессиональных технических писателей: запрещается использовать сленг, никаких личных местоимений, сокращений и лирических отступлений, всё строго по правилам русского литературного со всей мощью его причастных и деепричастных оборотов.

Когда-то довелось читать соответствующую методичку со списком примеров как «надо» и как «не надо», и сразу стало ясно, что тех.писателем мне не быть.

Это точно. Когда-то было желание перевести OpenGL Specification, но быстро понял, что или переводить придётся «своими словами» со всякими популярными жаргонными оборотами, или получится жуткий канцелярит.

ноуп, в том то и дело. я не жду от документации ни сленга, ни личных местоимений. корявые двусмысленные предложения

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

во-вторых, я хоть и читаю документацию исключительно на енглише, но

Читать не англ. документацию как то непрофессионально.

это чистейшее школотунство. Непрофессионально не уметь внятно объяснить зарубежную технологию на родном языке. Людей, которые говорят «Темплейты зааплоадил а деплоймент с ворнингами сегфолтнулся», я вполне понимаю и приемлю, но сам стараюсь избегать такого сленга. Чай не субкультура.

Что же должна представлять документация

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

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

своя :)

а из сторонних сходу могу вспомнить только ffmpeg.

Не самая отстойная, но больше всего матерных слов потрачено на Facebook SDK для iOS.

во-первых, от российской компании я жду внятной русской документации, это просто-напросто логично

Документация должна быть на английском и точка! Что за дурь ещё, если каждый будет писать документацию на китайских, русских, японских программист должен быть полиглотом каким то.

документация в первую очередь должна быть на родном языке автора и на енглише.

Зачем тратить время на родной язык автора? Что бы недопрограммисты не понимающие технический английский могли побыдлокодить? Не лучше ли уделить больше внимания нормальной документации а не тратить время на бессмыссленные переводы.

«Темплейты зааплоадил а деплоймент с ворнингами сегфолтнулся», я вполне понимаю и приемлю, но сам стараюсь избегать такого сленга

Я вот очень долго думал что такое «шаблон». А как бы вы произнесли данную фразу? Сдаётся мне получится значительно длиннее.