Джо Брокмейер (Joe "Zonker" Brockmeier), недавно покинувший пост лидера сообщества разработчиков openSUSE, опубликовал заметку (http://ostatic.com/blog/wheres-the-summer-of-documentation) в которой посетовал, что Google следовало бы провести наряду с "Summer of Code" инициативу "Summer of Documentation", в которой привлечь молодежь к процессу документирования кода, написанию качественных руководств, переводу на другие языки и улучшению дизайна
пользовательского интерфейса. По мнению Джо на вопрос, чего не хватает открытому ПО, один из наиболее частых ответов - "документации".URL: http://ostatic.com/blog/wheres-the-summer-of-documentation
Новость: http://www.opennet.me/opennews/art.shtml?num=26303
Как будто к проприетарщине больше документации...
ну вот к win32 GDI, к примеру, её _как минимум_ на порядок больше, чем к иксам
Осталось только найти мазохистов которые будут под гольные иксы программить :D
Под иксы документации - пяток толстеньких книжечек от O'Reilly плюс подробные описания ключевых библиотек и протоколов X11 в комплекте дистрибутива (объемистые такие pdf'ки).Вы мне лучше покажите мазохистов, которые в 2010 году будут программить под Win32 GDI, без MFC и прочих дотнетов.
>Как будто к проприетарщине больше документации...хелпы там нормальные
Речь не о хелпах, а о документировании кода. Да, в опенсорсе бывает его совсем нет и это очень ужастно
>Речь не о хелпах, а о документировании кода. Да, в опенсорсе бывает
>его совсем нет и это очень ужастноречь в новости абсолютно обо всем включая translators, user interface designers, artists,
а самое слабое место это обычно хелпы, потому что - TONS of documentation that many people simply CAN'T slog through.
>а самое слабое место это обычно хелпы, потому что - TONS of
>documentation that many people simply CAN'T slog through.вы не рвзработчик на сколько я понимаю... иначе вряд ли такое бы написали. Help можно написать, а вот использовать более-менее сложную библиотеку без комментированного кода нереально. Если вы конечно не обладаете даром телепатии.
>>а самое слабое место это обычно хелпы, потому что - TONS of
>>documentation that many people simply CAN'T slog through.
>
>вы не рвзработчик на сколько я понимаю... иначе вряд ли такое бы
>написали. Help можно написать, а вот использовать более-менее сложную библиотеку без
>комментированного кода нереально. Если вы конечно не обладаете даром телепатии.всё правильно, + примеры использования, тоже адски важны.
>Речь не о хелпах, а о документировании кода. Да, в опенсорсе бывает его совсем нет и это очень ужастноЗачастую можно обходиться и без подробной документации, ибо есть исходники. Особенно, если код писан по стандартам GNU - читать его одно удовольствие.
>Зачастую можно обходиться и без подробной документации, ибо есть исходники. Особенно, если код писан по стандартам GNU - читать его одно удовольствие.Сплю и вижу домохозяйку, которая читает исходники дабы понять как работает программа...
По нажатию F1, не хэлп, а сразу исходник программы открывает!
>Сплю и вижу домохозяйку, которая читает исходники дабы понять как работает программа...При чем здесь домохозяйка-то? Речь зашла об исходниках, а это явно не для домохозяек. :-)
>>Речь не о хелпах, а о документировании кода. Да, в опенсорсе бывает его совсем нет и это очень ужастно
>
>Зачастую можно обходиться и без подробной документации, ибо есть исходники. Особенно, если
>код писан по стандартам GNU - читать его одно удовольствие.и много сорцов ты прочитал и понял без телепатии? Неужели в ваших гнутых стандартах нет требования комментировать код... я очень удивлюсь если так
>и много сорцов ты прочитал и понял без телепатии? Неужели в ваших
>гнутых стандартах нет требования комментировать код... я очень удивлюсь если такДа немало. И регулярно читаю. Где-то есть комментарии, где-то нету. Когда код хорошо оформлен обычно и без комментариев все понятно.
Например, что делает функция gtk_tree_view_get_selection легко понятно из без телепатии. :-)
реализацию математики почитайте
Сплю и вижу человека, который юзает (к примеру) OpenSSL, руководствуясь исходниками. Смешно, ей-богу...
полность согласен
Большинство кода дают большие компании и в отсутствии док есть логика. Код открыт и бесплатен, кто ниасилил прочитать код и разобраться как работает платит за поддержку. Пока красноглазые приверженцы меряются крутизной дистров умные дядьки деньги зарабатывают.
>кто ниасилил прочитать код и разобраться как работаетфункции должны быть документированы, читать все исходники, чтобы понять какая функция нужна для выполнения необходимого действия - чистое красноглазие
А автор пробовал разрабатывать что-нибудь сам?
Есть и проекты с хорошей документацией. Пример - PostgreSQL, там документация на 2000 страниц в pdf формате.
На sendmail вон более 1200 страниц описания
и что кто-то активно пользует?
согласен, отличная документация у mediawiki а худщая у zend framework
У многих проектов с документацией проблемы. Особенно с локализованной. Справка к GIMP переведена лишь частично.
Из-за этого у нас внедрение в учебный процесс тормозится.
Переводы вечно устаревшие и неактуальные, в реальности никто их не будет поддерживать в актуальном состоянии в свободных проектах, как бы этого ни хотелось г-ну Джо Брокмейеру. Поэтому хотите пользоваться компьютером - извольте знать хотя бы технический английский.
Да, к сожалению. Многие лидеры проектов еще не поняли, что даже если код компилируется не на компьютере, а в голове, и не с Си, а с английского, он не менее важен, чем тот, который в компьютере, и должен, блин, быть частью проекта, а не "сопровождением". Особенно когда проект открытый.
>Да, к сожалению. Многие лидеры проектов еще не поняли, что даже если
>код компилируется не на компьютере, а в голове, и не с
>Си, а с английского, он не менее важен, чем тот, который
>в компьютере, и должен, блин, быть частью проекта, а не "сопровождением".
>Особенно когда проект открытый.Заурядный программист пишет код, понятный компилятору, хороший - код, понятный другому программисту.
А очень хороший еще и документацию к коду.
всё так, локальные викисы и сам пишу, и в других приветствую.
Я так понимаю, открытые исходники недостаточно документированы по сравнению с закрытыми?
Ну, давайте посмотрим на закрытые исходники, поучимся у них документированию)
А где закрытые исходники?
Нету.
Т.е. Брокмейер сетует только по поводу того, на что можно посмотреть.
Посмотрел бы он на документированность закрытого кода...)А документация к программе...
Мистеру Брокмейеру стоит указать на команду man, которая дает возможность почитать не только документацию к программам, но даже к функциям языков (man malloc).В остальном я бы сказал, что на документацию всегда можно найти время.
Если один человек будет заниматься только документацией, он сможет немало написать)
Нужно просто исходить из позиции "это нужно сделать".
Документированный код — это не обязательно комментарии в исходниках. Новость перечитайте.
>Документированный код — это не обязательно комментарии в исходниках. Новость перечитайте.Ну, если вы про man'ы, то с этим лучше, чем во многих проприетарных программах.
А перевод на другие языки страдает, как у опенсурса, так и у клозедсурса.
Не могу сказать, у кого страдает меньше.
Если только разделить проекты по крупности и сравнивать в своей весовой категории.
>Ну, если вы про man'ы, то с этим лучше, чем во многих
>проприетарных программах.
>А перевод на другие языки страдает, как у опенсурса, так и у
>клозедсурса.Перевод вопрос отдельный, в новости тоже разделено. А маны это только часть документации:
$ man openoffice
No manual entry for openoffice$ man firefox
(сами оцените информативность;)и т.д. Для гуевого софта нужны обычные хелпы, а их часто или нет, или недостаточно наполнены, или не локализованы, или и то, и другое.
"Серьезность проблемы пренебрежения открытых проектов процессом документирования"забористо
А причём тут вообще "пренебрежение"? Трольвадс же сказал: "for fun", а какой фан писать доки?!? Каждый мнит себя кульхацкером и пишет код не для того, чтобы его потом скурпулёзно вылизывать и документировать - добьются компиляции, запустят перделку - всё, фан получен, сорсы - в массы! :) Или я ошибаюсь?А по мне не в доках дело, а в инструментах - чем примитивнее язык (С/С++), тем сложнее докапываться до логики (хотя она КАК БЫ очевидна). Это как с часами - вроде бы все колёсики на виду, но ни черта непонятно! :)) Так что надо двигаться в сторону C#/D, там хоть поменьше кодомусора.
Ну и ещё момент: многие библебатеки написаны чуть ли не на заре линупса, некоторые - свежие, но опять являются чьим-то "портoм", в результате этот тухлокод поддерживается годами, совместимости ради. Перепроектировать этот хлам никому не интересно (а коммерч. компаниям и не выгодно), так что мегабайты обросших библиотек кочуют из дистра в дистр, затрудняя и компиляцию, и переносимость и даже улучшение. Либа более, чем в 500Кб кода - уже не поддающийся осмыслению монстр, так что даже доки тут не панацея - "вся проблема в головах".
>Так что надо двигаться в сторону C#/D, там хоть поменьше кодомусора.Глупости все это. Если привык оформлять код как придется, то на любом языке получится мусор.
Я "домохозяйка" и я хочу владеть документацией на родном языке.
Я хочу настраивать свою систему как хочу.Я не хочу болтаться по
идиотским форумам ,видя ,идиотские советы "учи американски".
Не хочу долбитсься с Google-переводчиком.
И я готов пожертвовать деньги для хорошего перевода.
не вопрос. 200$ за 40 тыщ знаков, предоплата 50%. Да, и заказчик должен быть на Украине или в США. Устраивает?
сорри, про минимальный объем забыл добавить. 5 х 40 000 тыс. зн.