Подготовка документов с использованием шаблонов Word и Writer от developerWorks

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

Добро пожаловать, авторы! Из этой статьи вы узнаете, как готовить англоязычные технические статьи и учебные пособия (туториалы) к публикации на центральном сайте developerWorks с помощью Microsoft® или OpenOffice.org Writer. Всё довольно просто. Сначала необходимо скачать пакет шаблонов для Word или Writer и заполнить в них соответствующие поля, а затем скомпоновать свою статью или учебное пособие согласно указаниям шаблона. В этой статье также приведено несколько советов по поводу того, как лучше форматировать материал и как передать его на рассмотрение в developerWorks.

Хотите использовать XML-шаблоны вместо шаблонов для текстовых процессоров?

Подготовка документов с использованием XML-шаблонов от developerWorks

Начало работы

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

Статьи и учебные пособия публикуются на developerWorks в HTML-формате, но генерируются они из формата XML (Extensible Markup Language – Расширяемый язык разметки). Редактор developerWorks будет конвертировать созданный вами документ Microsoft Word или OpenOffice.org Writer в наш XML-документ. Успешность этого преобразования во многом зависит от того, насколько предложенный вами Word- или Writer-документ следует указаниям шаблона.

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


Шаблон статьи или шаблон учебного пособия?

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

Учебные пособия

  • Пособия предназначены для обучения. В них не только приводится какая-то определённая последовательность шагов, но также объясняется, почему она делается так, а не иначе, и как это позволяет достичь основной цели. В пособиях приводится список рассматриваемых вопросов, а также указывается время, необходимое для изучения материала (обычно около двух часов). Освоивший учебное пособие читатель должен уметь самостоятельно решать задачи, аналогичные рассмотренным в пособии.
  • В пособиях могут излагаться концепции или способы решения каких-либо задач. Во многих учебных пособиях рассматривается и то и другое, что побуждает читателя параллельно с чтением пробовать решать стоящую перед ним задачу. Чтобы облегчить освоение материала в пособиях часто приводятся примеры кода и советы читателю по установке программных сред. Материал в пособиях часто разбивается на отдельные более простые подзадачи.
  • Использовать пособия могут только зарегистрированные пользователи.
  • Пособия имеют размер в среднем 20-30 печатных страниц. И, так как на решение поставленной задачи может потребоваться несколько часов, многие читатели распечатывают их PDF-версии, чтобы пользоваться ими как во время, так и после решения стоящих перед ними задач.
  • Пособие может публиковаться как само по себе, так и являться частью серии.

Статьи

  • Как и пособия, статьи почти всегда чему-то обучают, но не так углублённо. В статьях предварительно не излагается список рассматриваемых вопросов и не указывается время, необходимое для освоения материала.
  • Некоторые статьи не только помогают читателю решить какую-то конкретную задачу, но и знакомят его с последними концепциями, архитектурными решениями и новыми возможностями программных продуктов. Такие статьи призваны повысить компетентность читателя и вызвать у него интерес к более подробному изучению вопроса (возможно, посредством прочтения учебного пособия developerWorks!). Статьи другого типа имеют более «агитационный» характер: в них автор делится своим уникальным подходом к тому или иному вопросу, прогнозами или полезным опытом. Существует ещё одна разновидность статей: в них проводится подробное исследование какого-нибудь нового программного продукта или технологии, обычно в формате общения с экспертом или обзора текущей литературы по данной тематике.
  • Статьи доступны без регистрации.
  • Статьи в среднем содержат не более 10 печатных страниц. Читатели по большей части читают их через Интернет.
  • Как и пособие, статья может публиковаться сама по себе или как часть серии.


Основные этапы

Процесс создания статьи или пособия состоит из следующих этапов. Необходимо:

  1. Скачать пакет подготовки документов для Word или Writer (см. ниже в разделе Загрузка) и разархивировать его.
  2. Создать свой собственный шаблон статьи или пособия в Word или Writer, воспользовавшись шаблоном или скопировав образец.
  3. Отредактировать полученную статью или пособие, добавив свой материал, следуя указаниям шаблона или образца.
  4. Отправить свою статью или пособие вместе с файлами рисунков, исходных кодов и т.п. своему редактору на developerWorks.

Этап 1. Загрузка пакета подготовки документов

Скачайте файл Word author-package zip, если используете Word под Windows®, или файл Writer author-package zip, если используете Writer под Windows или под Linux®. Скопируйте его в удобную папку (например, в C:\ под Windows или в домашнюю директорию под Linux) и распакуйте.

После этого вы должны увидеть директорию (или папку) developerworks, содержащую подпапку word-templates или writer-templates, в зависимости от того, какой пакет вы скачали.

Файлы и инструменты, включённые в пакет подготовки документов, спроектированы для использования их под Linux или под Windows. Если вам требуется помощь в редактировании шаблонов под операционной системой, отличной от Windows и Linux, обращайтесь к вашему редактору developerWorks.


Что нового?

Прежде чем перейти ко второму этапу, давайте посмотрим, что нового появилось в этой версии пакета подготовки документов. Версия 5.9 для Word и Writer была выпущена 21 сентября 2007 г. Шаблоны в этих пакетах соответствуют версии 5.9 XML-схемы developerWorks и таблицам стилей. Следует подготавливать статьи и пособия, используя для этого пакет подготовки документов для Word или Writer версии 5.9. Если вы используете более раннюю версию, то вам необходимо скачать файл 5.9 author-package-xxxx.zip из раздела Загрузка (см. ниже).

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

Внешние изменения, представляющие интерес для авторов, отражены в обновлённых шаблонах статей и учебных пособий. Вот они:

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

Этап 2. Создание статьи или учебного пособия

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

Шаблон
Если вы уже имеете опыт подготовки материалов для developerWorks, то, вероятно, предпочтёте начать с наших шаблонов. При открытии шаблона вам будет предложено заполнить несколько полей данными, необходимыми developerWorks (см. таблицу 2 ниже), и только после этого будет показан основной материал с инструкциями.
Образец
Если вы впервые пишете для developerWorks, то мы рекомендуем вам использовать образец оформления статьи или пособия. Используя образец, можно сразу же начать работать с материалом. Необходимые для developerWorks данные будут заполнены значениями по умолчанию, так что вам придётся обновить их, прежде чем отправлять материал редактору.

Чтобы создать свою собственную статью или пособие, откройте соответствующий файл из списка в таблице 1.

Таблица 1. Шаблоны и образцы статей и учебных пособий
Шаблон или
образец
ПрограммаСтатья или
пособие
Файл
ОбразецWordСтатьяsample-article-word-5.9.doc
Пособиеsample-tutorial-word-5.9.doc
WriterСтатьяsample-article-writer-5.9.odt
Пособиеsample-tutorial-writer-5.9.odt
ШаблонWordСтатьяarticle-word-5.9.dot
Пособиеtutorial-word-5.9.dot
WriterСтатьяarticle-writer-5.9.ott
Пособиеtutorial-writer-5.9.ott

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

Таблица 2. Поля, которые требуется заполнить
tb-rowtb-row
ПолеОбязательное?Описание содержимого
Date (дата)ОбязательноеДата написания материала.
Type of Submission (тип заявленного материала)ОбязательноеСтатья или пособие. Выберите из выпадающего меню.
Title (заголовок)ОбязательноеЗаголовок статьи или пособия.
Subtitle (подзаголовок)НеобязательноеПодзаголовок статьи. Не обязателен, но рекомендуется.
Keywords (ключевые слова)НеобязательноеКлючевые слова статьи или пособия, используемые поисковым движком.
Prefix (префикс имени)НеобязательноеПрефикс вашего имени. Например: Dr., Mr., или Ms.
Given (имя)ОбязательноеВаше имя, например: John
Middle (второе имя)НеобязательноеОдно или несколько ваших вторых имён или инициалы от них. Например: D. (Для русскоязычных авторов здесь следует указать отчество)
Family (фамилия)ОбязательноеВаша фамилия. Например: Doe
Suffix (дополнение к имени)НеобязательноеДополнение к имени. Например: мл. или IV
Job Title (название должности)ОбязательноеВаша должность. Например: старший программист
Email (электронная почта)ОбязательноеАдрес вашей электронной почты.
Bio (краткая автобиография)ОбязательноеВаша краткая автобиография с указанием опыта работы и достижений, характеризующих вас как авторитетного специалиста по данной тематике.
Company (компания)ОбязательноеНазвание компании, в которой вы работаете. Например: IBM
Photo filename (имя файла фотографии)НеобязательноеИмя файла с вашей фотографией до плеч, которой можно будет сопроводить краткую биографию.
Abstract (резюме)ОбязательноеКраткий обзор статьи. В начале резюме укажите ключевые моменты и фразы статьи, так как вследствие усечения именно они будут отображены в результатах поиска. Напишите 3-5 предложений, указывающих на то, что именно может заинтересовать читателя в вашей статье, и какую пользу он сможет извлечь из прочтения этого материала.

Сохраните новый документ, задав ему имя по вашему усмотрению. Если вы работали с шаблоном, то не забудьте также сохранить его как обычный документ (с расширением .doc для Word и .odt для Writer), а не как шаблон.


Этап 3. Редактирование статьи или пособия

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

Советы по написанию материала

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

  • Можно копировать и вставлять фрагменты из ранее созданных документов, однако при этом необходимо следить, чтобы импортированные вместе с ними стили соответствовали нашим примерам.
  • В образцах приведены примеры наиболее часто встречающихся конструкций, используемых в статьях и пособиях на developerWorks. Если ваш материал не предполагает наличие каких-либо конструкций, скажем списка элементов (list) или рисунков, то не следует добавлять их только потому, что они есть в образце.
  • При включении листинга в текст статьи или пособия:
    • Ограничивайте длину строк листинга 90 символами, ВКЛЮЧАЯ пробелы.
    • Ограничивайте размер листинга 100 строками, ВКЛЮЧАЯ пустые строки.
    • Удаляйте жёстко прописанные пробелы или символы табуляции в конце строк листинга.
    • Не используйте символы табуляции в начале строк листинга. Если требуется создать отступ, то делайте это с помощью пробелов.
    • Не используйте выделение цветом. Если требуется выделить фрагмент кода, воспользуйтесь жирным шрифтом.
  • Чтобы сделать исходные коды примеров доступными в разделе Загрузка, заархивируйте их в формате zip и отдельно отправьте полученный zip-файл своему редактору.
  • Весь иллюстративный материал, в том числе снимки экрана, оформляйте как .jpg- или .gif-файлы, убедившись, что их размер в ширину не превышает 572 пиксела для статей и 500 пикселов – для пособий. Файлы иллюстраций также отправьте своему редактору. Посмотрите статью "Иллюстрирование статей и пособий на developerWorks", чтобы узнать подробнее о том, как создавать и эффективно доводить до читателя графический материал.

Правила выделения текста

Как следует выделить название книги: курсивом или кавычками? Когда использовать жирный шрифт, а когда вообще лучше никак не выделять текст? В таблице 3 приведены правила выделения текста, рекомендуемые для статей и пособий, публикуемых на developerWorks.

alt-rowalt-rowalt-rowalt-rowalt-rowalt-rowalt-rowalt-rowalt-rowalt-rowalt-rowalt-rowalt-rowalt-row
Таблица 3. Рекомендуемые правила выделения текста
Выделяемый элементРекомендуемый способ выделения
"Заголовки статей"Кавычки
Названия книгКурсив
Код C/C++Шрифт Courier или Courier New
КлассыШрифт Courier или Courier New
Код примеров
Стиль Стандартный HTML (Шрифт Courier или Courier New, 8 пт)
Фрагменты кода (меньше одной строки) встречающиеся в текстеШрифт Courier или Courier New
Названия рубрик или серийКурсив
Имена командШрифт Courier или Courier New
Имена директорийНе выделяются
Интонационное выделениеКурсив. Например: "Вводите ограничительные условияименно так. Не используйте для этого..."
Названия исключенийШрифт Courier или Courier New
Имена файловНе выделяются
Вызовы функцийШрифт Courier или Courier New
Управляющие элементы графического пользовательского интерфейсаЖирный шрифт. Например: "В меню установки щёлкните по: Установка нового дополнения > Завершить".
HTML-теги и фрагменты HTML-кодаШрифт Courier или Courier New
ИнтерфейсыШрифт Courier или Courier New
Ключевые слова (такие как static)Шрифт Courier или Courier New
Названия журналовКурсив. Например: "См. статью по данной тематике в LinuxToday".
Текст сообщений или запросов, адресованных пользователюШрифт Courier или Courier New
МетодыШрифт Courier или Courier New
ОбъектыШрифт Courier или Courier New
Полные имена файла (включающие путь)Не выделяется
Определённые в контексте терминыКурсив
Текст, введённый пользователемШрифт Courier или Courier New
"Названия учебных пособий"Кавычки
Типы данных (такие как int или long)Шрифт Courier или Courier New
URL-адресаНе выделяются
ПеременныеКурсив, например: "..., где mynameсодержит ID пользователя..."
XML-теги и фрагменты XML-кодаШрифт Courier или Courier New

Этап 4. Отправка статьи или пособия на developerWorks

Когда работа над материалом завершена, пора передать его вашему редактору на developerWorks. Отправьте ему по электронной почте свой Word- или Writer-файл со статьёй или учебным пособием, сопроводив его необходимым графическим материалом и исходными кодами примеров. Подробные указания и советы по созданию иллюстраций, а также по поводу того, как передать их своему редактору, вы можете получить, ознакомившись со статьёй "Иллюстрированием статей и учебных пособий на developerWorks".

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


Загрузка

ОписаниеИмяРазмер
Пакет IBM developerWorks для Word V5.9author-package-word-V5.9_20070919.zip249KB
Пакет IBM developerWorks для Writer, V5.9author-package-writer-V5.9_20070919.zip378KB

Ресурсы

Научиться

Получить продукты и технологии

Обсудить

  • Форма предложения материала (EN): представьте на рассмотрение редактору developerWorks идеи вашей будущей статьи или учебного пособия и начните общение с ним. Ознакомьтесь с перечнем интересующих тем ( content wish list (EN)), чтобы узнать, какой материал наиболее востребован на developerWorks.
  • Контактная информация редакторов developerWorks (EN): в случае возникновения вопросов свяжитесь с редактором того раздела developerWorks, который наиболее близок по тематике вашему материалу.

Комментарии

developerWorks: Войти

Обязательные поля отмечены звездочкой (*).


Нужен IBM ID?
Забыли Ваш IBM ID?


Забыли Ваш пароль?
Изменить пароль

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Профиль создается, когда вы первый раз заходите в developerWorks. Информация в вашем профиле (имя, страна / регион, название компании) отображается для всех пользователей и будет сопровождать любой опубликованный вами контент пока вы специально не укажите скрыть название вашей компании. Вы можете обновить ваш IBM аккаунт в любое время.

Вся введенная информация защищена.

Выберите имя, которое будет отображаться на экране



При первом входе в developerWorks для Вас будет создан профиль и Вам нужно будет выбрать Отображаемое имя. Оно будет выводиться рядом с контентом, опубликованным Вами в developerWorks.

Отображаемое имя должно иметь длину от 3 символов до 31 символа. Ваше Имя в системе должно быть уникальным. В качестве имени по соображениям приватности нельзя использовать контактный e-mail.

Обязательные поля отмечены звездочкой (*).

(Отображаемое имя должно иметь длину от 3 символов до 31 символа.)

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Вся введенная информация защищена.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=40
Zone=XML, Технология Java, Linux
ArticleID=292444
ArticleTitle=Подготовка документов с использованием шаблонов Word и Writer от developerWorks
publish-date=02292008