Глава 2. Начало работы

Содержание

Начните с того, что у вас уже есть
Выберите хорошее название
Разработайте четкое программное заявление
Подтвердите Что Проект Свободный
Функциональные возможности и Список требований
Текущее состояние разработки
Загрузки
Контроль версий и доступ к системе учета ошибок.
Каналы связи
Руководство разработчика
Документация
Доступность документации
Документация разработчика
Примеры выходных данных и снимки экранов
Постоянный хостинг
Выбор лицензии и ее применение
Лицензии "Делай что угодно"
GPL
Как применять лицензию к вашему программному обеспечению
Задавая тон
Избегайте закрытых обсуждений
Пресекайте грубость на корню
Практикуйте Открытое Рецензирование Кода
Открывая Изначально Закрытый Проект Будьте Внимательны к Значимости Изменений
Announcing

Классическая модель того, как начинаются проекты бесплатного программного обеспечения, предоставлена Эриком Раймондом, в теперь уже знаменитой статье о процессах разработки с открытым исходным кодом, озаглавленной Собор и Базар. Он писал:

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

(из http://www.catb.org/~esr/writings/cathedral-bazaar/ )

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

Большинство свободных проектов все еще начинаются именно так, но сейчас реже, чем в 1997, когда Раймонд написал эти слова. Сегодня у нас есть явление организаций — включая коммерческие корпорации— начинающих большие, централизованно управляемые проекты с открытым исходным кодом, с нуля. Одинокий программист, строча код для решения локальной задачи и потом понимая, что результат работы имеет более широкую применимость, все еще является источником большого количества нового свободного программного обеспечения, но не единственным

Тем не менее, точка зрения Раймонда все еще проницательна. Основным условием является то, что производители программного обеспечения напрямую заинтересованы в его успехе, потому что они сами его используют. Если программное обеспечение не делает того, что оно, как предполагается, должно делать, то человек или организация его производящая, будет чувствовать неудовлетворенность своей ежедневной работой. Например, проект OpenAdapter (http://www.openadapter.org /), который был начат инвестиционным банком Дресднер Клеинуорт Уоссерштеин (Dresdner Kleinwort Wasserstein) как ифраструктура с открытым исходным кодом, предназначенная для интеграции несовместимых финансовых информационных систем, едва ли способен вызвать зуд у любого самостоятельного разработчика. Она вызывает организационный зуд. Но этот зуд возникает непосредственно из опыта организации и ее партнеров,и поэтому если проект будет не в состоянии вылечить его, они об этом узнают. Такое положение дел способствует производству хорошего программного обеспечения, потому что цикл обратной связи идет в нужном направлении. Программа не писалась для того, чтобы быть проданной кому-то другому, так чтобы они могли решить их задачу. Она писалась для того, чтобы решить свою собственную задачу, а затем поделиться со всеми, как будто задача была болезнью, а программное обеспечение было лекарством, чье распространение означает полное истребление эпидемии.

Эта глава о том, как представить новый свободный программный проект миру, но многие из его рекомендаций, показались бы знакомыми органам здравоохранения, распространяющим лекарства. Цели очень похожи: вы хотите объяснить, что делает лекарство, отдаете его в руки нужных людей, и убеждаетесь в том, что тот кто его получил, знает как его использовать. Но в случае с программным обеспечением, вы также хотите соблазнить некоторых получателей присоединиться к продолжающейся исследовательской деятельности по улучшению лекарства.

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

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

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

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

Но сначала оглянитесь

Прежде чем начинать проект с открытым исходным кодом обратите внимание на одно важное предостережение:

Всегда осмотритесь вокруг, чтобы узнать нет ли уже существующего проекта, который делает то, что вы хотите. Существует большая вероятность того, что какую бы задачу вы не хотели решить сейчас, кто-то хотел решить ее до вас. И если они решили ее и выпустили свой код под свободной лицензией, тогда сегодня для вас нет причины снова изобретать колесо. Конечно есть исключчения: если вы хотите начать проекта в учебных целях, то уже существующий код не поможет; или, может быть, проект о котором вы думаете настолько узкоспециален, что вы знаете о нулевой вероятности того, что кто-то еще это делал. Но в общем, нет смысла не поискать и отдача может быть огромной. Если обычные поисковые службы ничего не находят, попробуйте поискать на http://freshmeat.net/ (сайт новостей о проектах с открытым исходным кодом, подробнее о котором будет сказано позднее), на http://www.sourceforge.net/ и в разделе свободных программн Фонда свободного программного обеспечения http://directory.fsf.org/.

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

Начните с того, что у вас уже есть

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

И что теперь?

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

Что делает ее такой утомительной, так это то, что главным образом она состоит из организации и описания вещей, которые остальные уже знаютs— "остальные", то есть те, кто уже принимает участие в проекте. Таким образом, для людей, делающих эту работу, нет никакой немедленной отдачи. Они не нуждаются в файле README дающем краткий обзор проекта, ни в документе о дизайне или руководстве пользователя. Они не нуждаются в тщательно организованном дереве кода, соответствующем неофициальным, но широко распространенным стандартам распространения исходных кодов программного обеспечения. Каким бы способом ни был организован исходный код, он прекрасно им подходит, потому что они, в любом случае, уже привыкли к нему, и если код в принципе работает, они знают как его использовать. Для них даже не имеет значения, если фундаментальные архитектурные решения проекта остаются не описанными; с ними они также уже знакомы.

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

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

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

Выберите хорошее название

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

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

Хорошее название:

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

  • Легко запоминается. Никуда не денешься от того факта, что английский стал языком интернета по умолчанию: "просто запомнить" означает "просто для того, кто может читать по английски, чтобы запомнить". Названия, которые являются игрой слов, зависящей от произношения носителя языка, например, будут непонятны многим читателям, для которых английский не является родным. Если игра слов особенно хороша и незабываема, она, может быть, все еще стоит того; только имейте в виду, что многие люди, видя название, не услышат его в своей голове так же, как услышит его носитель языка.

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

    Ссылки, упомянутые ранее в «Но сначала оглянитесь» полезны для полезны для нахождения проектов, уже имеющих то имя, о котором вы думали. Свободный поиск торговых марок доступен на http://www.nameprotect.org/ и http://www.uspto.gov/.

  • Если возможно, доступно как доменное имя в .com, .net, и .org доменах вержнего уровня. Вам нужно выбрать один, вероятнее .org, и сделать его официальным сайтом проекта; два других должны перенаправлять туда и должны просто препятствовать тому, чтобы посторонние лица создавали путанницу с именами вокруг проекта. Даже если вы хотите держать проект на другом сайте (см. «Постоянный хостинг»), вы все еще можете зарегистрировать определенные домены для проекта и перенаправлять с них на сайт проекта. Это очень помогает пользователям иметь простой для запоминания URL-адрес.

Разработайте четкое программное заявление

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

Программное заявление должно быть конкректным, устанавливающим четкие границы, и, прежде всего, коротким. Вот пример одного хорошего, от http://www.openoffice.org/:

Для создания, в сообществе, лидирующего международного программного пакета для офиса, который будет работать на всех распространенных платформах и предоставлять доступ ко всем функциям и данным при помощи API (Application Programming Interface - интерфейс прикладного программирования), основанном на открытых компонентах и формате файлов, основанном на XML.

Всего в нескольких словах они указали на ключевые точки, широко основываясь на предыдущих знаниях читателя. Говоря "в сообществе", они указывают, что никакая корпорация не будет руководить разработкой; "международный" означает, что программное обеспечение позволит людям работать на разных языках и с различнимы региональными настройками; "все распространенные платформы" означает, что оно будет пренесено на Unix, Macintosh и Windows. Остальное говорит о том, что открытые интерфейсы и легко понимаемые форматы файлов являются важной частью намеченной цели. Они не выходят и не говорят прямо, что пытаются стать свободной альтернативой Microsoft Office, но многие люди, вероятно смогут прочитать это между строк. Хотя это программное заявление кажется слишком общим на первый взгляд, в действительности оно четко очерчивает круг задач: слова "пакет для офиса" означает предельно конкретную вещь для тех, кто хорошо знаком с подобным программным обеспечением. Опять, предполагаемые предыдущие знания читателя (в данном случае, вероятно, из MS Office) используются для сохранения краткости программного заявления.

Природа программного заявления зависит частично от того, кто его пишет а не только от программного обеспечения, которое оно описывает. Например, для OpenOffice.org есть смысл использовать слова "в сообществе", потому что проект был начат, и все еще в значительной степени спонсируется компанией Sun Microsystems. Включая эти слова Sun указывает на свое внимание к тревогам о том, что она могла бы попытаться руководить процессом разработки. При обращении с подобными вещами, простая демонстрация понимания возможного возникновения проблемы, ведет по пути полного ухода от нее. С другой стороны, проекты, которые не спонсируются одной единственной корпорацией вероятно, не нуждаются в таком указании; в конце концов, разработка сообществом — норма, и таким образом, обычно не бывает никакой причины указывать на это, как на часть программного заявления.

Подтвердите Что Проект Свободный

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

Главная страница должна однозначно ясно указывать на то, что это проект с открытым исходным кодом. Это может показаться очевидным, но вы были бы удивлены, насколько много проектов забывают это сделать. Я видел вебсайты проектов свободного программного обеспечения, где главная страница не только не говорила, под какой именно конкретной свободной лицензией распространяется программное обеспечение, но и вообще не указывала напрямую, что это свободное программное обеспечение. Иногда, решающий бит информации отправлялся в изгнание на страницу Загрузки, или на страницу для Разработчиков, или в любое другое место, которое требует лишнего щелчка мыши, чтобы до него добраться. В крайних случаях лицензия вообщен не была указана нигде на сайте — единственный способ найти ее состоял в том, чтобы загрузить программное обеспечение и посмотреть внутри.

Не совершайте такой ошибки. Подобное упущение может привести к потере многих потенциальных разработчиков и пользователей. Укажите наверху, сразу под программным заявлением, что проект является "свободным программным обеспечением" или "программным обеспечением с открытым исходным кодом", и предоставьте точную лицензию. Быстрое руководство по выбору лицензии дается в «Выбор лицензии и ее применение» далее в этой главе, а возможные проблемы с лицензиями подробно обсуждаются в Глава 9, Licenses, Copyrights, and Patents.

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

Функциональные возможности и Список требований

Там должен быть краткий список функций, которые поддерживает программное обеспечение (если что-то еще не закончено, вы можете включить это в список, но поместить "запланировано" или "в разработке" рядом с ними), и тип вычислительной среды, требуеющейся для работы программного обеспечения. Подумайте о списке функций/требований как о чем-то, что вы предоставили кому-нибудь, попросившему краткое описание программного обеспечения. Это, часто, всего лишь логическое развитие программного заявления. Например, программное заявление могло бы сказать:

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

Список функциональных возможностей и требований давал бы подробные объяснения, проясняя область применения, описанную в программном заявлении:

Функциональные возможности:

  • Поиск в простом тексте, HTML и XML

  • Поиск слова и предложения

  • (запланировано) Нечеткое совпадение

  • (запланировано) Инкрементное обновление индексов

  • (запланировано) Индексирование удаленных веб-сайтов

Требования:

  • Python 2.2 или выше

  • Достаточное дисковое пространство для хранения индексов (примерно в два раза больше изначального объема данных)

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

Текущее состояние разработки

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

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

Не бойтесь выглядеть неготовым и не поддавайтесь искушению раздуть текущее состояние. Все знают, что программное обеспечение развивается постепенно; нет ничего постыдного в том, чтобы сказать "Это - альфа-версия программного обеспечения, содержащая известные ошибки. Оно выполняется, и работает, по крайней мере, время от времени, но используйте его на ваш собственный риск." Такое заявление не будет отпугивать тот тип разработчиков,которые нужны вам на этой стадии. Что касается пользователей, одна из самых плохих вещей, которые может сделать проект - это привлекть пользователей прежде, чем программное обеспечение для них будет готово. Очень трудно отделаться от приобретенной когда-то репутации неустойчивого или нестабильного проекта. Консерватизм окупается в долгосрочной перспективе; для программного обеспечения всегда лучше быть более стабильным, чем ожидает пользователь, чем менее, и приятные неожиданности способствуют лучшим отзывам.

Загрузки

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

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

Это кажется очевидным, но многие проекты не потрудились стандартизировать свои операции по установке почти до окончания игры, говоря самим себе, что они могут это сделать в любое время: "Мы уладим все это когда код будет близок к завершению." Чего они не понимают, так это того, что откладывая скучную работу по доведению до ума процедур сборки и установки, они фактически увеличивают время на завершение кода— потому что они отпугивают разработчиков, которые, в ином случае,дополнили бы код. Но самое коварство заключается в том, что они не знают , что они теряют всех этих разработчиков, потому что этот процесс - накопление непримечательных событий: кто-то посещает веб-сайт, загружает программное обеспечение, пытается его собрать, терпит неудачу, сдается и уходит. Узнает ли кто-нибудь когда-нибудь, что это случилось, кроме самого этого человека? Никто работающий над проектом не поймет, что чей-то интерес и добрая воля были тихо растрачены.

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

Когда вы выпускаете пакет, доступный для скачивания, жизненно важно присвоить уникальный номер версиии этому выпуску, чтобы люди могли сравнить два любых пакета и узнать какой из них заменяет другой. Подробное обсуждение нумерования версий можно найти в «Release Numbering», а подробности стандартизации процессов сборки и установки в «Packaging», оба в Глава 7, Packaging, Releasing, and Daily Development.

Контроль версий и доступ к системе учета ошибок.

Скачивание исходных пакетов прекрасно подходит для тех, кто хочет просто установить и использовать программное обеспечение, но этого недостаточно для тех, кто хочет его отладить или добавить новые возможности. Ночные версии кода могут помочь, но они все еще не являются достаточно разделенными на модули для бурно развивающегося сообщества разработчиков. Людям нужен доступ к последним версиям кода в реальном времени, и средством обеспечения такого доступа является использование системы управления версиями. Наличие анонимно доступных исходных кодов с контролируемыми версиями, это указание— и пользователям и разработчикам— на то, что проект позаботился о том, чтобы дать людям все что им нужно для учестия в проекте. Если вы не можете предложить систему управления версиями сразу же, то сделайте пометку, указывающую на то, что вы намерены вскоре ее настроить. Инфраструктура управления версиями подробно обсуждается в «Version Control» в Глава 3, Техническое обеспечение.

Тоже самое каксается и проектной системы отслеживания ошибок. Важность системы отслеживания ошибок заключается не только в ее полезности для разработчиков, но и в том, что она значит для тех, кто наблюдает за проектом. Для многих людей, доступная база данных об ошибках является лучшим показателем того, что к проекту можно относиться серьезно. Более того, чем большее количество ошибок содержится в базе данных, тем лучше выглядит проект. Это может показаться парадоксальным, но вспомните, что количество зарегистрированных ошибок зависит от трех факторов: абсолютного числа ошибок, содержащихся в программном обеспечении, числа пользователей, работающих с программным обеспечением и удобства, с которым эти пользователи могут регистрировать эти ошибки. Из этих трех факторов два последних более значимы, чем первый. Любое программное обеспечение достаточного объема и сложности, содержит в высшей степени случайное число ошибок, ожидающих, чтобы их нашли. Настоящий вопрос в том, насколько хорошо проект регистрирует и выставляет приоритеты этим ошибкам? Проект с большой и хорошо поддерживаемой базой данных об ошибках (это значит, что реакция на ошибки своевременна, дублирующиеся ошибки сведены к одной и т.д.), таким образом, производит лучшее впечатление, чем проект совсем без базы данных об ошибках и с почти пустой базой данных.

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

Заметьте, что системы учета ошибок используются для слежения не только за ошибками в программном обеспечении, но и для заявок на расширение функциональных возможностей, изменений в документации, ожидающих реализации заданий и многого другого. Подробности работы с системой учета ошибок описаны в «Bug Tracker» в Глава 3, Техническое обеспечение, так что здесь я не буду рассматривать ее здесь. С точки зрения представления проекта важно просто иметь систему слежения за ошибками и убедиться в том, что факт ее наличия отражен на главной странице проекта.

Каналы связи

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

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

Так как эта глава только о том, как начать проект, то достаточно сказать, что эти форумы для общения должны существовать. Позже, в «Управление ростом» в Глава 6, Общение, мы рассмотрим где и как устанавливать такие форумы, случаи, в которых они могут нуждаться в модерировании и другом обслуживании, и как отделить форумы для разработчиков от форумов для пользователей, когда придет время, избежав создания непреодолимой пропасти.

Руководство разработчика

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

Эта тема подробно рассматривается в «Writing It All Down» в Глава 4, Социальная и политическая инфраструктура, но основнымми элементами руководства разработчика являются:

  • указатели на форумы для взаимодействия с другими разработчиками

  • инструкции о том, как сообщать об ошибках и присылать исправления

  • некоторые советы по тому, как обычно ведется разработка — является ли проект добровольным диктаторством, демократией, или чем-нибудь другим

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

Смотрите http://svn.collab.net/repos/svn/trunk/www/hacking.html как пример очень досконального руководства разработчика или http://www.openoffice.org/dev_docs/guidelines.html как более свободного руководства, которое больше сосредоточено на направлении и духе участия, и меньше на технических тонкостях.

Проблема предоставления программисту введения в программный проект отдельно обсуждается в «Документация разработчика» далее в жтой главе.

Документация

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

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

Нет никакого волшебного решения этой проблемы. Кто-то просто должен сесть и написать текст, а затем следовать ему, как типичный новый пользователь, чтобы проверить его качество. Используйте простой, легкий в редактировании формат, такой как HTML, простой текст, Texinfo, или какой-то вариант XML— что-нибудь, что удобно для легковесных, быстрых, моментальных исправлений. Это нужно не только для того, чтобы исключить любые лишние трудности, которые могли бы препятствовать первоначальным авторам вносить последующие изменения, но также и для тех, кто присоединяется к проекту позже и хочет работать над документацией.

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

  • Четко объясните читателям какой уровень технических знаний от них ожидается.

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

  • Предоставьте в стиле обучающей методики пример того, как выполнить одну частоиспользуемую операцию. Очевидно, что множество примеров для множества задач было бы еще лучше, но если время ограниченно, выберите одну задачу и тщательно пройдитесь по ней. Как только кто-нибудь увидит, что программа может быть использованна для одного действия, они начнут изучать, что еще она может делать сама по себе—и, если вам повезет, станут дополнять документацию сами. Что приводит нас к следующему пункту...

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

Последний пункт, на самом деле, имеет более широкое значение, и может быть применен ко всему проекту, а не только к документации. Точный учет известных недостатков, это норма в мире открытого исходного кода. Вам не нужно преувеличивать недостатки проекта, просто указать на них, тщательно и беспристрастно, когда этого требует контекст (или в документации, или в базе данных об ошибках, или в обсуждении в списке рассылки). Никто не будет рассматривать это ни как пораженческое настроение со стороны проекта, ни как стремление, решить проблему к определенной дате, если только проект явно не заявит о подобной цели. Так как каждый, кто использует программное обеспечение, сам по себе обнаружит неточности, для них намного лучше быть психологически подготовленными— тогда будет похоже на то, что проект обладает точным знанием того, как он себя чувствует.

Доступность документации

Документация должна быть доступна в двух местах: в интернете (напрямую с сайта), и в загружаемом пакете программного обеспечения (см. «Packaging» в Глава 7, Packaging, Releasing, and Daily Development). Она должна быть в интернете в виде просматриваемого списка, потому что люди часто читают документацию до того как скачивают программу первый раз, рассматривая ее, как подсказку, чтобы решить стоит ли ее загружать вообще. Но она также должна сопровождать программу, по принципу того, что загружаемый пакет должен предоставлять (т.е. делать локально доступным) все что нужно человеку для использования пакета.

Для документации в интернете, убедитесь, что присутствует ссылка, которая ведет к полной документации на одной HTML странице (сделайте пометку "единая" или "все-в-одном" или "одна большая страница" рядом со ссылкой, чтобы люди знали, что загрузка может занять некоторое время). Это полезно, потому что люди часто хотят поискать определенное слово или фразу по всей документации. В общем, они уже знают, что они ищут; они просто не помнят в какой секции это оно находится. Для таких людей, не ничего более разочаровывающего, чем увидеть одну HTML страницу для оглавления, затем другую для вступления, затем другую для для инструкций по установке и т.д. Когда страницы разбиты таким образом, функция поиска в их браузере бесполезна. Стиль раздельных страниц полезен для тех, кто знает, какая секция им нужна или тем, кто хочет прочитать последовательно всю документацию от начала до конца. Но это не самый распространенный способ, которым используют документацию. Гораздо чаще, кто-либо, знакомый с основами программы возвращается, чтобы поискать отпределенное слово или фразу. Отказать им в предоставлении единого, доступного для поиска документа, сделает их жизнь только тяжелее.

Документация разработчика

Документация разработчика пишется для того, чтобы помочь программистам понять код, и чтобы они могли исправлять и расширять его. Она несколько отличается от руководства разработчика, обсуждавшегося ранее, которое более социальное, чем техническое. Руководство разработчика говорит программистам, как взаимодействовать друг с другом; документация разработчика говорит как взаимодействовать с самим кодом. Оба вида документов часто складываются вместе в один документ для удобства (как, например, в http://svn.collab.net/repos/svn/trunk/www/hacking.html указанном ранее), но это не обязательно.

Хотя документация разработчика может быть очень полезной, нет никакой причины задерживать выпуск продукта, чтобы ее доделать. До тех пор, пока изначальные авторы документации могут (и хотят) отвечать на вопросы о коде, этого достаточно для начала. Фактически, необходимость отвечать на те же самые вопросы снова и снова является самой частой причиной для написания документации. Но даже до того, как она написана, определенным участникам проекта удается пробираться через код. Сила, заставляющая людей тратить время, изучая основы кода, это то, что код делает для них что-то полезное. Если у людей есть такая вера, они найдут время чтобы разобраться; если у них этой веры нет, никакое количество документации для разработчика их не привлечет и не удержит.

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

Некоторые проекты используют wiki как начальную документацию, или даже как основную документацию. По моему опыту, в действительности это работает только если wiki активно редактируется несколькими людьми, которые договорились, как документация должна быть организована и какой "голос" должен у нее быть. Смотрите «Wikis» в Глава 3, Техническое обеспечение подробнее.

Примеры выходных данных и снимки экранов

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

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

Постоянный хостинг

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

Смотрите «Canned Hosting» в Глава 3, Техническое обеспечение где более детально обсуждаутся преимущества и недостатки постоянного хостинга и приводится список сайтов, которые его предлагают.