О документации

[metaclass]

Опен-сорсным проектам нужно на пару лет прекращать доработки кода за исключением security и поддержки текущего состояния смежных проектов, и занятся документацией.
А особенно - зачисткой гугла от 100500 копий сообщений в списках рассылки, дубликатов wiki и тому подобного, по устаревшим версиям библиотек.
Потому что сейчас любой вопрос гуглу возвращает информацию начиная от 2004 года(а то иногда и раньше), которая устарела как неизвестно что.
А когда язык развивается быстрее, чем гугл успевает индексировать - то разобраться, скажем, что clojure.contrib уже не модно использовать, практически нереально.

Comments

[raydac.livejournal.com]

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

[metaclass.livejournal.com]

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

[nicka-startcev.livejournal.com]

а вот, кстати, не всегда.
Например, у фриварного када (OpenSCAD) документация в онлайне на удивление приличная, как по содержанию так и по форме. Даже родным оглавлением пользоваться удобнее, чем гуглем.

[raydac.livejournal.com]

ну дак вполне вероятно, но к сожалению такие вещи это исключительные случаи, а бездокументность это общее правило теперь (((

[nicka-startcev.livejournal.com]

бездокументность это еще не самое страшное.
Гораздо страшнее когда есть несколько гигабайт документации в которой ничего невозможно найти.

типаприиер.
Давным-давно, когда вин95 уже было, а вин98 еще нет, захотелось мне написать виндовую игрушку 'life'. то есть, просто поле в котором я программно что-то рисую, подпись, пара кнопок. я решил сделать это на вин32апи. Потратил порядка месяца на блуждание по мутному и запутанному мсдн. а задача-то была простая, тупо и цинично перерисовывать "карту" выбирая цвет каждой точки в зависимости от циферки в предрассчитанном массиве.

Что интересно, лет через 15, когда аналогичную задачу решал на SDL, мне понадобилось меньше дня, хотя у SDL документация по объёму порядка этак на три меньше, чем вин32апи раздел MSDN.

[raydac.livejournal.com]

имхо мутная документация это лучше чем отсутствие таковой, так как из наличия чего то можно что то извлечь, но из отсутствия нельзя извлечь ничего

[nicka-startcev.livejournal.com]

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

а МСДН сильно смахивает на труды маркса-ленина-мао, которые постфактум всё объясняют, но практически не помогают в практической разработке.

[raydac.livejournal.com]

главное что к МСДН не надо прикладывать живого сотрудника микрософта писавшего API и как показывает практика, разобраться можно

[theiced.livejournal.com]

нельзя. нужна сотня говнокнижек и пара гурей рядом.

[metaclass.livejournal.com]

Не, я по msdn смог разобраться)

[nealar.livejournal.com]

Это называется "ниасилил"

[metaclass.livejournal.com]

Я по MSDN дохера чего переписал, по winapi там еще куда ни шло дока. Правда, старый хелп еще в .hlp формате тогда был удобнее.
А вот когда в MSDN засунули все, что есть у микрософта - искать стало гораздо сложнее, оно на каждую фразу выдает ее вариации для всего, начиная от Windows CE и заканчивая VB и встроенными функциями редкоиспользуемых расширений MSSQL

[nicka-startcev.livejournal.com]

ну, я на тот момент так и не асилил полную схему действий для "изобразить произвольную картинку".
а потом уже неактуально было.

[nicka-startcev.livejournal.com]

кстати, одно время МСДН шел на дисках и можно было не ставить лишнее, поставить, например, только вин32апи и не натыкаться на лишнее.

кстати, хехе, как в этом вашем мсдн найти все статьи, содержащие строку "\\.\" ? :) я от этой особенности поиска долго матерился.

[metaclass.livejournal.com]

Ты попробуй такую строку в гугле найти. У нас тут народ матерился от этого так, что никакому MSDN не снилось)

[nicka-startcev.livejournal.com]

в гугле та же фигня, да. И в яндексе.

[nealar.livejournal.com]

Я до сих пор матерюсь от того, как гугол работает со знаками препинания

[nicka-startcev.livejournal.com]

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

[metaclass.livejournal.com]

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

[nicka-startcev.livejournal.com]

а в простых предметных областях что, нет 'выделенных центров' с вменяемыми авторами?

[metaclass.livejournal.com]

Нет, потому что слишком много людей осилило и использует)

[nicka-startcev.livejournal.com]

кстати, в этом опенскаде всякое школиё делает всякие хоз-быт-фигнюльки типа вот такой: http://www.thingiverse.com/thing:8945 или вот таких http://www.thingiverse.com/featured/page:1

то есть, проект вполне популярный.

[avnik.livejournal.com]

У pyramid документация более чем на уровне (и из нее же печатается книжка, с продаж которой финансируется разработка). Но ребе не осилил петон...

[nicka-startcev.livejournal.com]

я тоже питон не осилил. Я не вижу зачем он нужен лично мне прямо сейчас. У меня сейчас другие интересы.