Большая часть документации в интернете — отстой. Полный Отстой! Это при условии, что она вообще есть. Да, есть очень редкие исключения: Django, Python (в некоторой степени), но их исчезающе мало.
Отчего так? От того, что у большинства программистов скилл формулирования мыслей, скажем честно, развит хреново. А тем, у кого он таки развит, чаще всего очень лень. "What docs? Use the Source, Luke!"
У меня есть на этот счет идея...
GitHub, LaunchPad и BitBucket успешно показывают, что если программистам дать удобный общественный source control, то они начнут коммитить туда код, активно форкаться, мерджиться и обсуждать все происходящее прямо там же. Кажется очевидным, что синергетически усиленный результат тут отличается от того, что было раньше, когда каждый проект сидел на своем обособленном наборе инструментов.
Сдается мне, что то же самое должно сработать и для документаторов. Представьте себе эдакий Doc(Hub|Pad|Bucket).net:
Сайт — большая wiki. Типа Wikipedia, но только заточенная на написание документации. Открыта для всех. Не нашел человек документации на грешный pynotify, погуглил, понарыл примеров, а потом пошел на сайт и создал документацию по этой библиотеке.
Общая структура для всех проектов: главный тьюториал, прикладные тьюториалы, референс, how-to, примеры. Все это желательно находить в предсказуемых местах и предсказуемом виде.
Импорта исходников для создания скелета справочников по API.
Автоматический импорт с обновлением официальных документаций с официальных сайтов. Пусть у Django есть документация на своем сайте, но пусть она будет и на этом сайте тоже. Почему нет? Тут она сможет обрасти, например, комментариями (у Postgres'а такое например есть).
Удобный дизайн, работающий поиск.
Социальные фички. Иначе вы туда не пойдете участвовать :-). Например можно визуализировать и всячески поощрять развитие известных wiki-ролей (wiki-гномы, wiki-воины и пр.)
Самая большая проблема — я понятия не имею, как с такого сайта можно собирать деньги :-). Ведь поднять такое на энтузиазме очень-очень сложно... Наверное потому такого и нет еще. Но вот если кто решит этот вопрос, то спрос и ломовая посещаемость будут гарантированы.
Комментарии: 40
Ну, посещаемость неплохо конвертируется в деньги рекламой. А уж ломовая - и вполне незаметной рекламой.
Идея отличная и интересная. И, действительно, можно попробовать.
Обычно в таких случаях для FOSS разработчиков всё бесплатно, тогда как для проприетарного софта необходимо платить за аккаунты. По крайней мере, так устроен bitbucket.
Кстати, теоретически всё же этом можно и в bitbucket интегрировать.
Для Ruby/Rails что-то похожее есть - http://apidock.com, но гипер активности там не наблюдается
Хе, не мне одному не спится.
Хорошая идея-то.
А в чем проблема с доходами? Уже написали выше, что реклама начнет приносить доходы, если посещаемость будет большой.
И подобный сайт в принципе неплохо раскручивается - авторы разных программ будут рады поставить ссылку на такой сайт чтобы избавить себя от тяжкого труда по документированию )))
Ссылка на Python ведёт на Postgres.
Для руби и рельсов есть APIdock http://apidock.com/ . Оно правда всего лишь с заметками, а не в виде вики, но все равно очень полезно.
С заработком хороший вопрос. Гитхабовцы писали, что они до сих пор ничего для себя не заработали. Все деньги улетают в поддержку самого сайта
http://wikibooks.org ?
ответ на твой вопрос достаточно прост и лежит в корне процветания гугла как финансовой импении.
Контекстная реклама! ведь если отвлечься от питона и постгри, где признаю чесно мне сложно придумать что рекламировать, кроме решений, можно написать документацию по телевизорам и рекламировать продажу оных! :)
Идея для стартапа? ;)
Мой прогноз — все более-менее скоро решится усовершенствованием поддержки документации в GitHub и аналогах. Уже сейчас там есть wiki и автоматическое отображение readme-файлов. Сделают в дополненние к этому автоматическую генерацию API reference из исходников для большинства популярных языков и стадартную структуру докуменов, о которой ты пишешь — 90% потребностей будет закрыто.
Ну и никуда не денется тот факт, что для несерьезных open source проектов документация все равно будет слабой. Все-таки ее написание — дело достатоно скучное и, как правило, требует дополнительной мотивации.
Зарабатывание денег рекламой на таком сайте — не годится, имхо. Привлечь коммерческие (закрытые) проекты тоже нечем — для них никаких проблем писать документацию в том же sphinx'е: разработчики-то фулл-тайм работают, им не нужен интерфейс "быстро написать две строки документации".
Была похожая идея (да и есть собственно), как вариант монетизации рассматривал предоставление того же сервиса коммерческим разработчикам в private-режиме за некоторую плату.
Sphinx — это тулза, а я говорю о публичном редактировании. Этого в коммерческих компаниях нет. И надо сказать, то, что разработчики работают там full-time, не помогает: документация на коммерческие системы тоже по большей части полный отстой. Так что им это тоже надо.
в комерческих системах системах, особенно с большим количеством изменений и кучей доработок со стороны заказчиков ( а особенно если количество аказчиков больше 1-2х) документация вообще не развита. обычно размножается копипастом и мало информативна, я уже не говорю о том, что редко совпадает с реальностью.
Не, про системы для конкретных заказчиков речь тут не идет. Им вообще не нужна публичная документация. Я про системы (неважно, коммерческие или нет), которые для общего использования предназначены.
С публичной документации деньги не соберешь — чем она отличается от опенсорсовой документации?
P.S. Написал длинный коммент и из-за неаккуратности его протерял. :( Впрочем, и без него можно обойтись. ;)
Вот в том вопрос и есть. Как собирать деньги с опенсорсовой документации :-)
Документация к cakephp представляет из себя что-то подобное.
Дмитрий Дзема написал:
Дайте ссылку на оригинал, пожалуйста.
Иван, мой (не очень большой) опыт подсказывает, что достаточного количества желающих просто НЕ найдется. Энтузиазм быстро гаснет, а доки — это много рутинной работы.
К тому же: что мешает человеку написать в своем блоге мини-доку? Она будет проиндексирована поисковиками. Если дока хорошая, то со временем ее будут находить часто.
@bialix
Упс, что-то я напутал с гитхабом. Когда писал думал об этой презентации. Но я что-то перпутал. Он там пишет, что они profitable. Извиняюсь за ложную информацию
Истребляют уже существующую документацию? Не сгущайте краски :-)
В основном с документацией всё в порядке, по крайней мере, для работы вполне хватает. Стандартные вещи (как правило) описаны на сайте производителя, нестандартные (тоже как правило) кем-то уже обсуждались и было найдено решение, поиск которого через гугл или яндекс не составляет особого труда.
Смущает разрозненная документация? Хотите собрать её в одном месте? А кому это нужно? Для большинства пользователей сайт Doc(Hub|Pad|Bucket) будет ещё одним источником, на который будет ссылаться гугл. Ну а самое главное: как Вы собираетесь привлекать людей к написанию документации?
ИМХО, Doc(Hub|Pad|Bucket) будет невостребованным.
будет братская могила устаревших HOWTO
хорошие вики у генту и арча
Странно, что никто не упомянул документацию PHP. Всегда считал её эталонной
http://docs.php.net/manual/en/index.php
А я думаю стоит сделать что-то базовое, чтобы попробовать идею.
В мире такое количество сумасшедших, почему не попробовать?
Рассказать кому-то идею BitBucket'a или Twitter'a пару лет назад - ну точно бы на смех подняли.
Коммерческие компании заинтересованы, чтобы информация на их продукты обновлялась добровольцами, со временем они сами будут использовать что-то подобное для себя. Для коммерческих компаний абонплата, для опенсурса - бесплатно + ненавязчивая реклама (баннеры на сайте, контекст).
Интересно.Поставил на контроль.
Идея прекрасная, конечно.
Вот занялся я написанием спецификации на паука своего, прежде чем переписывать на очередной сетевой бекенд. Дал коллеге с превосходным знанием английского почитать, мол, исправить ошибки всякие. А github ему - регистрация, регистрация. Может добрый человек проходил мимо, сделал бы доброе дело. А так и пройдет мимо.
Кстати есть же всякие campfire, lighthouse и пр. багтрекинг сервисы. Наверно, и такие как ты предлагаешь тоже будут.
Сам же сверху нопесал, шо подавляющее большинство open source программистов не умеют и/или не любят песать документацию.
Именно в этом одна из неразрешимых проблем open source, а наличие ещё одной специализированной wiki ничо не изменит.
скромное мнение:
нет смысла в таких обобщениях.
действительно, есть же гугль.
тем более если автор будет пытаться, "поднять" что либо с коммерсантов..или заработать на чем либо..
то такой проект рано или поздно примет коммерческий аспект за основу.
и прекрасно,что есть много "сумасшедших",делящихся познаниями на страницах блогов и т.д децентрализовано.
Хм... а почему в заметке написано "импорта", а не "импорты"... Претензия на скилл по формулированию соутсов? Кошмар!
Шикарная идея.
И собственных наблюдений (возможно ошибочных) замечу - Есть много форумов по разной тематике. Первоначально, на форумах активно задают вопросы и охотно на них отвечают. Проходит время форум зарастает и становится похож на свалку мусора. Участники перестают отвечать на вопросы, зная что ответ есть где то на форуме и посылают гуглить. В итоге и вопросы перестают задавать. В моем понятии форум умер лично я ищу другой.
К чему это я о форумах, предлагаю подумать над вопросами...
То есть, "форумо-чат" с "флудо-трепом" о жизни, на первом месте а на втором, вики справочник.
Каждый участник может внести свою лепту в справочник и повысить свою репутацию.
Будут посетители, будут деньги (реклама в меру не помешает).
А форум посещают чаще - вики справочника. Или вопрос о стартовых деньгах?
p.s. Хотя, если смотреть с позиции "Легкого" заработка, идея гиблая.
наличие каких либо профессиональных навыков в любой сфере,
вряд ли позволяют вам,Сергей,
называть даже чайника - бездарем.
а лень - эт святое.
лень двигатель всего.
будьте пожалуйста снисходительны,
к людям не обладающим вашего уровня знаний в какой либо сфере.
тем более доки пишутся для них.
ведь вы тоже - чайник в какой либо сфере.
(для примера в шахматы могу предложить сыграть)
Да, такая централизованная система с документацией была бы очень кстати. Думаю на рекламе не хуже сурсфоржа могла бы зарабатывать - ведь при соответствующем количестве проектов, кликов то будет гораздо больше...
Иван, УЖЕ существует система, и не одна,
которая позволяет создавать КАЧЕСТВЕННУЮ
документацию, агрегирующую в себе знания
из различных источников и опыт лучших профи,
причём делающая это за деньги.
Примеры:
O'Reilly, Manning, WROX, и т.д. и т.п.
Создать хорошую документацию ОЧЕНЬ трудно.
Эта работа ОЧЕНЬ СЛАБО оценивается
спесивыми снобами программистами.
Поэтому я считаю правильным выпускать документацию
в виде книжек и брать деньги с программистов,
которые сами документацию писать не умеют и гордятся этим.
Пусть гордятся на здоровье и платят деньги людям,
которые знают как делать качественные книжки.
Кстати, книжки по GNU/OpenSource продуктам,
равно как тренинги и мастерклассы, -
один из значимых источников заработка вокруг GNU/OpenSource.
Т.е. в части окупаемости качественной документации
всё уже открыто!
Не надо изобретать велосипед!
Если хочется подвига - изобретите мопед:
прикрутие экспорт в DITA к wackowiki.
У вас в яндексе используют обе технологии,
но не сопрягли их ещё, насколько я понимаю.
Технические писатели скажут вам спасибо.
Прикрутите DITA к WackoWiki
и издайте книжку в Manning напару с Романом Ивановым:
"WackoWiki and DITA documentation development -
single sourcing approach".
А Георгия Благодатова в редакторы возьмите :)
И будет людям счастье,
и вам тоже будет счастье.
PS
MoinMoin wiki - плоха по разным причинам,
одна из эти причин - DocBook.
К сожалению, документация только в виде книжек страдает плохой доступностью. Если я скачал поиграться библиотечку, мне нужна документация прямо сейчас, я не могу ждать месяцок книжку с Амазона, потому что интерес у меня уже пропадет.
Если DITA - это http://dita.xml.org/, то я тогда не очень понял предложение :-). DITA — это же не набор документации?
Заметка мне понравилась.
Есть отличная книга "Producing Open Source Software" про то, как делали SVN. Так вот в ней рассказывается, как быть с wiki, что делать с форумом, списком рассылки и прочей документацией.
Проблема не в документации, проблема в активном сообществе, которое надо поддерживать и развивать. Ведь документация - это способ решить проблему пользователя. Важный, но не единственный. А вот активное сообщество - это сила, которая может реально помочь. Путем доводки документации в том числе.
А вот на сообществе уже можно заработать.
Почему-то не получается добавить ответ. Забанили?
Ну так можно PDF-ки раздавать за небольшие деньги.
Впрочем, вопрос-то не в том, как монетизировать
процесс создания документации,
а, скорее, в том,
как мотивировать разработчиков
на создание действительно хорошей документации.
Мотивация не всегда равна монетизации.
Хотя и связаны, конечно.
Вспоминаю мемуары Л.С.Понтрягина (советский математик),
который очень добросовестно и тщательно
подготавливал учебные пособия к печати.
Он писал, что зарабатывает в 4 раза меньше,
чем автор-халтурщик.
Почему в 4 раза меньше?
4 = 2*2
Первая двойка - объём текста в печатных листах.
Издательство платит за печатные листы.
Тщательно проработанный и продуманный текст
занимал примерно вдвое меньший объём,
чем первоначальная "быстрая и грязная" версия,
а именно такие версии отдавали
в издательство авторы-халтурщики.
Таким образом, улучшая текст
многопроходным редактированием, Л.С.Понтрягин
уменьшал в 2 раза не только объём текста,
но и сумму оплаты по сравнению с суммой,
которую получал автор-халтурщик.
(Не помню,чтобы Понтрягин упоминал
конкретные имена авторов-халтурщиков.
Безымянны, как "обычный стиральный порошок в телерекламе,
да оно и понятно.)
Вторая двойка - время, затрачиваемое на создание текста.
Чтобы создать качественный текст,
Л.С.Понтрягин затрачивал вдвое больше времени
по сравнению с автором-халтурщиком.
В итоге, за единицу затраченного на текст времени
Л.С.Понтрягин получал вчетверо меньше денег,
чем пресловутый халтурщик.
Не понял вас.
Darwin Information Typing Architecture - это,
скорее, методика (формализованная в DTD и XML Schema),
поддержанная инструментом разработки:
http://dita.xml.org/wiki/the-dita-open-toolkit
Более того, поддержка DITA XML
входит в известные средства работы с XML,
такие как oxygen или Syntext Serna.
Возвращаясь к программистам.
Личное наблюдение:
программист легко может писать внутри исходного кода
и, чуть труднее, в вики.
Технический писатель работает с DITA.
Микропропасть между программерами и техписами
помог бы преодолеть инструмент,
позволяющий выполнять экспорт:
Думаю, такой инструмент будет с благодарностью принят людьми,
создающими документацию.
Интересная заметка. К сожалению отвечаю сильно позже того времени, как Вы ее написали.
Меня тоже заботит документация и то, что часто ее нет.
я попробовал взглянуть на эту проблему под еще одним углом:
"А если дать разработчику удобный инструмент, который позволит править исходники доки, которые будут лежять тут же рядом в SVN?".
У разработчиков на Питоне есть почти идеальный тул — sphinx. Насколько я понял, там нехватает совсем небольшого приспособления: возможность просмотра текущего фрагмента документации без пересборки проекта и даже без явной компиляции страницы — просто зашел браузером и посмотрел, как в wiki. И тут же, прямо в браузере подправил.
Я написал такой инструмент на PHP и с прицелом на php-разработчиков: http://www.bulldoc.ru
Думаю это неплохая идея для плагина или инструмента для shpinx.
В качестве еще одной иллюстрации — похожий инструмент для ASCIIDoc, дискуссия на хабре