• Документации
• Bluebream
• BluebreamДляРазработчиков

Для разработчиков

Вклад в BlueBream

Если вы заинтересованы во внесении вклада в проект BlueBream, посетите вики страницу: http://wiki.zope.org/bluebream/ContributingToBlueBream

Ресурсы для разработчиков

• Исходный код управляется через репозиторий Zope. Вы можете вытянуть исходники из trunk следующим образом (анонимный доступ):

     1    svn co svn://svn.zope.org/repos/main/bluebream/trunk bluebream
  

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

• Блог проекта

• Баги отслеживаются на launchpad

• BlueBream Wiki

• Страница PyPI

• Documentation

• Twitter

• Список рассылки

• IRC канал: #bluebream на irc.freenode.net

• Buildbot

Процесс разработки

Создание релизов

Процедура создания релизов, которой следует BlueBream очень похожа на ту, которой следует ZTK.

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

Другими словами, перед началом релиза убедитесь в том, что:

• Все тесты пройдены
• Все локальные изменения поступили в репозиторий
• Журнал изменений (changelog) обновлен.

Пострелизные шаги

• Сделать объявление в списке рассылки
• Сделать запись в блоге
• Обновить статус в twitter

Список проверки релиза

Список проверки релиза на данный момент управляется через вики: http://wiki.zope.org/bluebream/ReleaseChecklist

Технические решения

• BlueBream - это “веб фреймворк”.

• Допускается сокращение BlueBream как Bream или BB. На данный момент сокращение BB становится все более популярным в сообществе.

• Есть только один публично доступный API известный как bluebream - пакет. Этот API - точка входа, предоставляемая setuptools, который использует PasteScript:

     1   entry_points={
     2   "paste.paster_create_template":
     3     ["bluebream = bluebream.bluebream_base.template:BlueBream",
     4      ]}
  

• Весь код фреймворка использует пространства имен для пакетов: zope или zope.app, хотя в будущем может использоваться и bb.

• проект bluebream состоит из шаблонов проектов.

• веб сайт bluebream - место хранения веб содержимого.

• bbkit - место хранения инфраструктуры KGS.

• BlueBream 1.0 должен обеспечивать переход с Zope 3.4 KGS.

• Любая команда оболочки (shell command), которая должна повторятся после создания проекта не автоматизируется через шаблон проекта.

• Запуск bootstrap.py и buildout в проекте не должны выполнятся во время создания шаблона проекта исходя из предыдущего пункта. Другая причина в том, что так проще работать с системами контроля версий.

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

Руководство по написанию документации

Обзор

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

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

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

Целью этих подсказок не является покрытие всех вариантов использования английского языка и ошибок построения текстов. Я считаю, что лучшим ресурсов по правилам построения текстов является The Elements of Style, автор William Strunk, Jr. Также доступно продолжение этой книги, отредактированное и дополненное автором E. B. White (и наиболее часто встречающееся в книжных магазинах). The Elements of Style - незаменимая книга для всех, чья задача - писать чистым английским языком. Хотя правила, которые здесь описываются, созданы под впечатлением, и часто совпадают, с правилами и концепциями, описанными в The Elements of Style, они направлены в первую очередь на написание документации к программному обеспечению, или всему, что является ему технически эквивалентным.

Вот несколько интересных ссылок на другие похожие ресурсы:

• English usage in Cyberspace

• Writer’s General Reference

Подсказки

Говорите прямо с читателем

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

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

• Когда мы добавляем новый метод в этот класс, он переопределит все методы с таким же именем, которые определены в наших подклассах.

Такое построение часто называют Королевское "Мы" (The Royal We). Поправить это можно простых изменением:

• Когда вы добавляете новый метод в этот класс, он переопределит все методы с таким же именем, которые определены в ваших подклассах.

Будьте напористым

Никогда не говорите в слабой, неопределенной, возможностной манере.

Как описано в The Elements of Style (правило #11), используйте активное состояние. Это настолько распространенная ошибка, что она стоит того, чтобы повторить ее здесь с несколькими примерами. Активное состояние значит взаимодействие с объектом, поданное с помощью глагола в активном состоянии. И наоборот, пассивное состояние, обычно, включаете описание состояния объекта, который постоянно делает какое-нибудь бесконечное действие. Например:

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

Вот те же предложения в активном состоянии. Заметьте, как приходится перестраивать предложения:

• Запомните, ZPublisher отказывается публиковать метод, который не имеет строки документации.
• Экраны, оформленные в виде закладок, обеспечивают стандартное соглашение для управления продуктом.

Никогда не говорите возможностными понятиями, как может быть, возможно, или наверное. Это зачастую является бессознательным действием при написании документации до того, как создано само программное обеспечение. Будьте напористым, и показывайте, как есть, а не как может быть. От возможно откажитесь вообще. Может быть и наверное могут быть заменены на есть. Должен также иногда подпадает под это правило.

Объясняйте ключевые идеи простыми понятиями

Документация должна объяснять читателю ключевые идеи. Часто эти идеи не очевидные для читателя, когда он использует программное обеспечение, поэтому требуют описания.

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

Когда читатель не понимает того, что написано в документации, это, обычно, из-за того, что он встречается с незнакомым или непонятным словом. Ясное объяснение включает построение ключевой идеи в уме читателя с помощью простых понятий, которые он способен воспринять. Когда вы подаете детали реализации перед объяснением ключевой идеи, читатель спотыкается; результатом становится недопонимание. Читатель пропускает техническую часть, которую он, на данный момент, не понимает, или не способен понять, потому что вы не закончили объяснение ключевой идеи. Например, первый параграф черновика пользовательской документации по методам Zope гласит:

• Все возможности Zope предоставляются методами, таким или иным образом. Когда вы запрашиваете URL у Zope, он сначала вытягивает объект из ZODB, а потом уже вызывает метод этого объекта. Методы встроенных Zope объектов определены в исходниках Zope, или в Python классах, которых хранятся в модулях продуктов в файловой системе. Дополнительные классы объектов (и их методы) могут быть определены путем создания продуктов в файловой системы, и это правильно, когда реализация класса требует расширенного доступа к ресурсам (таким как файловая система), которая должна быть тщательно защищена.

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

• Вы можете писать простые скрипты в Zope на языке программирования с помощью методов Python.

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

Предоставляйте простые примеры

Проза используется для объяснения ключевой идеи читателю. Примеры используются для того, чтобы показать идею в работе. Оба метода приветствуются; проза объясняет работу примера, а пример показывает работу конкретной технологии.

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

Избегайте разговорных выражений

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

• Настраивая интервал проверки интерпретатора для уменьшения частоты переключения контекста в Python, вы можете заставить Zope кричать.

Должно быть написано так:

• Настраивая интервал проверки интерпретатора для уменьшения частоты переключения контекста в Python, вы можете повысить скорость выполнения.

Предоставляйте ответы, не порождайте вопросы

Имеется ввиду вопрос, который следует незамедлительно после ответа. Например:

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

Вопрос служит только для представления концепции, а не как вопрос читателю. Подавайте концепцию прямо:

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

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

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

Пересмотрите предложения, которые говорят мало, или ничего

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

• С первого взгляда, оно кажется простым
• Вы должны начать сначала