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

[metaclass]

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

Comments

[nicka-startcev.livejournal.com]

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

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

[metaclass.livejournal.com]

>технологии типа-устаревают быстрее, чем их успевают допилить до рабочего состояния.
слава богу, хоть что-то можно не изучать)

Какая-то хреновая сингулярность, однако. Все, для чего она пригодна - одноразовые веб-2.0-сайты, задачки на прожект эйлер и выебоны в ЖЖ :)

[raydac.livejournal.com]

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

[metaclass.livejournal.com]

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

[nicka-startcev.livejournal.com]

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

[http://users.livejournal.com/zubr_/]

Поисковик проиндексировал.
Как заставить "забыть" проиндексированное? При условии, что оно продолжает храниться в виде "версии" и по-прежнему доступно?

[metaclass.livejournal.com]

Грохнуть старые ресурсы, написать на них и гугл сам про них забудет со временем

[trueblacker.livejournal.com]

ладно ещё библиотеки. Библиотеки ещё куда ни шло.
Но вот шаманские пляски вокруг линуксовых дистрибутивов 10 летней давности - они сейчас кому нужны?

[trueblacker.livejournal.com]

а гугля их выдаёт пачками

[metaclass.livejournal.com]

Да, документация по линуксу превратилась большей частью в тыкву.

[mend0za.livejournal.com]

> Но вот шаманские пляски вокруг линуксовых дистрибутивов 10 летней
> давности - они сейчас кому нужны?


Ну не скажите. Волшебные слова "legacy systems support". При мне одну бабку с пенсии отзывали, чтобы она счистила целебную плесень со своих знаний Cobol и PL/1 и написала транслятор с нейкого богом забытого забытого языка программирования на PL/1. Для мейнфрейма на System/390.

Тоже самое будет (и уже настаёт) для Linux. В частности, мне уже приходилось заниматься археологией вокруг умершей технологии EVMS, дабы портировать старую кодовую базу на другой/новый дистриб. Поддержка EVMS была выпилена из инсталятора две мажорные версии назад в связи со смертью апстрима (IBM прекратил оплачивать и бросил всё).

[veter-r-r.livejournal.com]

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

[swizard.livejournal.com]

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

Не надо вести никакую документацию, это провал. Язык должен быть самодокументируемым, рантайм должен иметь мощный RTTI, и среда должна быть глубоко интегрирована с рантаймом и иметь развитые возможности по навигации по коду.

Имея CL + slime я уже забыл, когда я зачем-либо лез в гугл для поиска информации по языку или библиотеке. Всегда к услугам describe, slime-inspect, slime-apropos, slime-apropos-package и навигация по slime-edit-definition. И, что самое ценное здесь, всё всегда де-факто актуально :)

Подозреваю, что для Closure всё это добро доступно. Надо просто освоить slime :)

[metaclass.livejournal.com]

Доступно, через swank

[theiced.livejournal.com]

ребе уже поставил емакс, всё в процессе.

[craneop.livejournal.com]

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

[avnik.livejournal.com]

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

[mend0za.livejournal.com]

Зачастую нетривиальные случаи можно найти только в мейллистах. И в багтраках сотв. проектов.

[metaclass.livejournal.com]

Да, большей уебищности сложно придумать.

[devnu11.livejournal.com]

>Потому что сейчас любой вопрос гуглу возвращает информацию начиная от 2004 года(а то иногда и раньше), которая устарела как неизвестно что.

ну так а что мешает указывать при поиске "за последний год" ?

[tonsky.livejournal.com]

Она не для ломанья головы, а для дела скорее. С++ да, для тех кому скучно и хочется поупражняться в остроте ума.

[guamoka.livejournal.com]

ИМХО, лишний раз подтверждает, что наличие такого количества недокументированного программного кода- это код ради кода. Он делает "всё то же самое, но с сиреневым оттенком". Соответственно, и документация- лишнее. Потому что авторы сами нихрена не знают, что же они пытаются сделать. И уж тем более у них нет слов, чтобы объяснить это:-) Известная проблема с кодерами. Чем "продуктивнее" кодер, тем сложнее у него с речевым аппаратом и изложением мыслей словами.
Кстати, вот еще одна распространённая мантра насчет "самодокументированного" кода. Это бляц пиздец несусветный, мем, вброшенный в мозги программистишкам, привыкшим делать "вещь в себе". Таким образом, полагается, что а) задачу можно решить одним единственным способом, поэтому код однозначно отражает постановку задачи (с хера ли?) б) исходный код- это не реализация решения- инструкция компилятору-машине, а вся проектировочно-дизайнерско-планировачная шняга в одном флаконе, необходимая для решения какой-то реальной задачи:-)

[tonsky.livejournal.com]

Боюсь, что авторы Кложи (о которой речь в посте) слишком хорошо понимают, зачем они что делают и какие задачи решают. Вот, к примеру: http://tonsky.livejournal.com/243192.html. Это вполне конкретные, серьезные и нерешенные проблемы, и они действительно ими успешно решаются. Рич Хики вообще один из умнейших программистов сейчас. Не работает ваше гадание на кофейной гуще.

[volger.livejournal.com]

А поиск в гугле с заданием диапазона времени не канает? Там же есть:
За всё время
За час
За 24 часа
За 2 дня
За неделю
За месяц
За год
За период...

[veter-r-r.livejournal.com]

О, читал все комменты, ожидая, что кто-то про это вспомнит.. и только в последнем комментарии увидел ожидаемое.

[demon-gloom.livejournal.com]

1. Документация часто устаревает, т.к. код а то и основное ядро пилется и меняется очень быстро. Значит проект не достиг еще какой то взрослости и код пишется как дышло, куда мысль повернет - туда и вышло.

2. Есть несколько толковых примеров в плане организации документации - http://docs.sencha.com/ext-js/4-0/ и сенчевский генератор документации (ничего более удобного из документаций не видел) и doxygen, который всеяден и тоже может при правильном коде построить всякие визуальные модели и доки для api.

3. Документировать логику что реально хотел выразить автор нет смысла. Если автор написал код который вызывает желание сразу выкинуть и переписать, то не факт что его задокументрованный алгоритм будет понятней.