Руководство по стилям для создания online гипертекста

Руководство создано для последовательного чтения, но Вы можете выбрать нужную Вам часть. Основные разделы руководства:

• Введение
• Этикет для администраторов сервера
• Общая структура работ
  • Структура для читателей
  • Деревья
  • Размер документа
  • Ссылка или копия
• Внутри каждого документа
  • Подпишитесь!
  • Дайте ему статус
  • Давайте ссылки на контекст
  • Хороший заголовок
  • Не форматируйте для конкретного просмотрщика
  • Думайте о том как это печатать
  • Сохраняйте читаемость текста
  • Избегайте технических деталей
• Тестируйте свой документ
• Дополнительное чтение
• Комментарии читателей

Чтобы напечатать этот документ

Этот документ открыт для комментариев!

Введение

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

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

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

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

Web этикет

• Подпись Вашей работы -- особенно welcome page;
• Определение статуса документа.

Welcome page для гостей

Welcome page - Home page?

Welcome page будет приветствовать новых пользователей, которые хотят познакомиться с содержанием Вашего сервера. Это послужит сходным целям для Вашей home page, но разница существует для тех, кому она адресована. Часто люди внутри организации используют welcome page как свою home page. В конечном счете они получают представление о том, как их организация выглядит для других людей. Я сам этого не делал, так как у меня много персональной информации на моей home page, которую я не хочу выставлять на welcome page организации или мою собственную welcome page, например, биографию. Welcome page может содержать раз'яснения того, что собой представляет Ваш сервер, что может стать пустой тратой пространства на Вашей home page для местных пользователей. Так что Вы можете захотеть создать отдельную home page для местных пользователей.

Псевдоним для Вашего сервера

В будущем [3/94] клиенты будут искать локальную "www" машину для использования welcome page, как home page, если в конфигурации явно не указано другое. Это означает, что кто угодно запускающий клиента внутри Вашего домена получит одинаковую начальную страницу.

Псевдоним для самого себя

Делегирование полномочий

Домашний стиль

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

Структура

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

Вы также должны иметь в виду:

• Читатели заранее должны представлять себе структуру
• Идея перекрывающихся деревьев
• Насколько большим должен быть документ
• Ссылка или копия

Структура для читателя.

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

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

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

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

Когда Вы делаете ссылку, обозначайте ее таким ключевым словом, чтобы некоторые люди могли пропустить ее. Например, "Если Вы действительно хотите узнать, как это работает, смотрите Internals guide", или "Введение step-by-step можно найти в обучающей части".

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

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

Перекрывающиеся деревья

			Обучение			Справочник
			   |				    |
	      Давайте знакомиться вместе	       -----------------
		от простого к сложному  	      |			|
			    |		      по Функциональным      Имена функций
			    |			    группам	  в алфавитном порядке
	  Примеры, ориентированные на задания	      |			|
			    |			       -----------------
			    |				    |
		  Примеры использования 		  Синтаксические определения
		  специфических функций   <-------->    для специфических функций

Насколько большим делать каждый документ

Документ может быть совсем малым по размеру. Например, это примечание.

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

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

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

Также они не приносят авторам неприятностей создания (или генерирования) большого количества связей и постоянного их обновления в случае изменения данных. Если создание ссылок является проблемой используйте в документе только одну ссылку - на страницу содержания. Некоторые просмотрщики имеют кнопки "next" и "previous", позволяющие просматривать документы по списку.

(Фактически, можно нормально просматривать длинные документы вверх и вниз последовательно страницу за страницей, но это создает впечатление, что Вы работаете с алфавитно-цифровым терминалом).

Приблизительным руководством по размеру документа может служить:

• Для online help, menu, дающих доступ к другим материалам лучше не превышать 24 линии. Проверьте это утверждение сидя за текстовым терминалом.
• Для текстовых документов - примерно 2.5 листа формата A4.

Ссылка или копия?

Имеется несколько причин оставить информацию на прежнем месте:

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

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

• Internet FAQ *Frequently Asked Questions) lists
• RFCs (Request For Comments -- Internet standards etc)
• Information by subject
• The "best" URLs on the web. Создайте личный список указателей Ваших интересов. Вам это пригодится!

Внутри каждого документа

Дополнения следуют (незаконченный раздел).

Вы должны попытаться:

• Подписывать свою работу
• Дать ей статус
• Делать ссылки на страницы контекста .
• Используйте независимый от контекста заголовок
• Формат, независимый от устройства вывода

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

Подписывайтесь!

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

Ваша авторская страница является традиционным местом помещения отказа от прав, заметок об авторском праве и т.д., требуемые законом или традициями. Это спасает сами Ваши заметки и послания от длинных подписей.

(Если Вы используете WorldWideWeb.app редактор гипертекста, Вы можете разместить эту ссылку из default blank page [пустая страница для редактора по умолчанию] так что она автоматически окажется в конце каждого нового документа)

Статус Вашей информации

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

Вы конечно можете дать оттенок статуса текста через его язык ... синтаксические ошибки, пропущенные заглавные буквы, "расслабленная" грамматика, все это указывает на неофициальность стиля. Осторожно используйте глаголы "shall" и "should" (для английского текста), а инструкция Long Capitalised Noun Phrases (LCNPs) в конце концов создаст впечатление изучения ISO стандарта. ;-)

Датируйте

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

Ссылайтесь на контекст

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

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

Навигационные рисунки (icons)

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

[This style guide was for a long time empty of icons because I was editing it with the old hypertext editor which doesn't handle images. I may fix that with time -tbl]

TITLE (Заголовок)

У любого документа может быть только один заголовок Он должен идентифицировать содержание документа в довольно широком контексте.

Заголовок не является частью текста документа, но он относится ко всему документу. Он не может содержать ссылок, меток параграфов или подчеркиваний. Заголовок может использоваться для определения строк в history list, для заголовков окон, показывающих отдельные документы, и т.д. Он обычно не отображается в тексте собственно документа. Этим различаются titles и headings. Идеальная длина заголовка - менее 64 знаков. Таким образом, многие приложения будут показывать заголовки документов в окне для заголовков, в меню, и т.д. - там, где место ограничено. Не существует ограничений на длину заголовков (так как они могут быть автоматически сгенерированными из других данных), но информационные провайдеры должны помнить, что слишком длинные заголовки могут обрезаться.

Примеры использования

		<TITLE>Rivest and Neuman. 1989(b)</TITLE>

		<TITLE>Рецепт сиропа Flap-Jack</TITLE>

		<TITLE>Introduction -- AFS user's Guide</TITLE>

		<TITLE>Инструкция</TITLE>

	<TITLE>Remarks on the Quantum-Gravity effects of "Bean
	Pole" diversification in Mononucleosis patients in Developing
	Countries under Economic Conditions Prevalent during
	the Second half of the Twentieth Century, and Related Papers:
	a Summary</TITLE>

Независимость от устройства

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

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

Например:

• Всегда используйте уровни заголовков в следующем порядке, один заголовок 1-го уровня в начале документа, если необходимо, то несколько заголовков 2-го уровня, и далее, если необходимо, несколько заголовков 3-го уровня внутри каждого заголовка 2-го уровня. Если Вам не нравится то, как форматируется заголовок 2-го уровня, настройте это в своем клиенте, но не перепрыгивайте на следующий уровень заголовков.
• Не делайте дополнительных пробелов или пустых линий в Вашем тексте только для "раздувания" документа, исключая преформатированную части (tag PRE).
• Не ссылайтесь в Вашем тексте на особенности определенного просмотрщика. Просить кого-то "нажмите здесь" не имеет смысл без мышки, также как и просьба кого-то "выберите ссылку по номеру" опровергается фактом того, что Вы используете не line-mode просмотрщик. Оставьте только ссылку. Инструкции излишни, если пользователь сам знает как выбирать ссылки.

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

Легко печатающийся гипертекст

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

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

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

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

Делайте Ваш (гипер)текст читаемым

Первое - это синдром _HERE_, т.е.:

	Информацию о Blah Blah Blah можно получить нажав _here_.

	Информация о _Blah Blah Blah_ теперь доступна.

	Информация о _способах поиска_ доступна.

	Если хотите получить информацию о способах поиска, выберите _эту ссылку_.

   	Здесь ссылки на страницы _КРЕДИТОВ_ и _технических деталей_

   	Огромное спасибо _различным людям_ за их содействие

Избегайте разговоров о механике

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

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

Даже если Вы работаете с метафорами web, используйте ссылки, но не говорите о них. Например:

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

		обучающая часть содержит больше информации об этом.

	Обучающая часть содержит разделы по mowing, sharpening the mower,
	и buying a mower.

	Обучающая часть содержит разделы по mowing, sharpening the mower,
	и buying a mower.

Тестируйте свой документ

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

Сколько времени отводить на тест?

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

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

Проверка Вашего HTML

Дополнительное чтение

• The HTML Specification и ссылки из него
• A Beginner's Guide to writing HTML
• World-Wide Web server software - список указателей
• Web Ettiquette -- для администраторов серверов The Web Designer, N Laviolette. Много ссылок

Reader comments

• Lutz Falkenhagen

• Robert Stockton

• Lars Aronsson
• Scott Nash

Примечание

Пример ссылки