[docs] Категоризация

Fr. Br. George george на altlinux.ru
Чт Янв 27 15:18:54 MSK 2005


On Thu, Jan 27, 2005 at 12:20:34PM +0300, Kirill Maslinsky wrote:
> Всем привет!
> 
> > От общей классификации не уйти, потому что необщая подразумевает десятки
> > пунктов. Предлагаю тогда классификацию АЕН:
> > * How (всё, что без объяснений: howto, инструкции, cookbook, таблички с
> >   командами и прочее)
> > * How & Why (всё, что с объяснениями: FAQ, руководства, учебники,
> >   методички, описания и прочее)
> > * "Why" (любые заявления, не касающиеся технических вопросов, или список
> >   требований к чему-то: полиси, реклама, анонсы, тексты _про_ сообщество
> >   и прочая идеология и т. п.)
> > * <Catch-all> Занимательное чтение
> Я против catch-all: пусть лучше по прочтении текста будет не очень понятно, 
> почему он попал в ту или иную категорию, чем вообще непонятно, что это 
> за текст и браться ли его читать. (Эпитет ``занимательное'' скептическому 
> уму может обоснованно показаться субъективным и потому неубедительным).
	В этом случае роль catch-all бдет играть _отсутствие_ категории.
Но ведь в Кучу текст положили? Зачем? А как искать тексты по
_отсутствующему_ свойству? Вот я и предлагаю его как-нибудь назвать.
Хотя бы один catch-all должен быть.
> > Надо категории переназвать, а то слишком поэтично, но идея понятна?
> Идея понятна, хотя есть опасения, что бОльшая часть текстов попадёт в 
> How&Why, потому что так чтобы совсем без объяснений -- бывает редко. 
	Ну нет, есть множество документов, в которых ничего не обясняется.
Любой краткий справочник таков. Для тех, кто наизусть не выучил, и не
желает, а в объяснениях не нуждается. Или наоборот -- инструкции по
эксплуатации. Или Howto (в смысле ``делай так-то, а почему -- RTFM'').
> Хотя это, наверное, и хорошо. Что касается названий... 
> Моя жена предложила такие: 
> 
> * Инструкции (how)
> * Индукции (от частного к общему: учебники, tutorials, и т. п. обучающие тексты)
> * Дедукции (от общего к частному: why&how, как обычно и бывает в хорошей документации)
> 
> Очень изящно, по-моему. 
	Получается, что если в учебнике сначала излагается теория, а
потом приводятся примеры, то он -- дедукция, а если сначала примеры, а
потом объяснения -- индукция? Это -- классификация по _стилю изложения_,
такая тонкость уж чересчур. В большинстве случаев используются оба
приёма.
	А главное, к какой категории относятся тексты типа "Why"? Они у
тебя просто делись в никуда (aka catch-all). Я не был уверен именно в
наименовании этой категории. Хотя сейчас мне кажется, что и так неплохо.
А, вот: в стиле твоей жены можно назвать это "декларациями"!

	[offtopic] Хорошая документация -- это не дедукция, а текст, с
помощью которого легко решить информационную проблему. И в зависимости
от проблемы он может быть организован любым способом.

> > Может, и в самом деле стоит поделить на рабочее место/сервер (он же и
> > офис, так как области задач примерно одинаковые). Или так, по источнику
> > задач:
> Офис в отдельный пункт я выделил, чтобы туда попали тексты, про то как сделать именно офис на линуксе, т. е. и серверы, и рабочие места, корпоративная сеть, словом. Конечно, в выделении офиса в отдельную категорию есть толика PR-а.
	Какой PR??? Мы обсуждаем паспорт документа в Куче!

> > * Для себя (про рабочее место, маленькие хитрости и т. п., игры)
> > * Для фирмы (когда задачи ставит начальство: административные дела,
> >   серверы, сеть)
> Минус классификации по источнику целей: одна и та же цель (например, организация smtp-сервера или списка рассылки и т. п.) может иметь источники самого разного характера. А как сделать -- один текст. 
Почему же разного характера? Все источники в этом случае -- внешние, но
с исполнителем лично связанные. Очевидно, что smtp-сервер редко когда
нужен ровно одному человеку (и уж никто не станет искать решение этой
задачи в разделе "для себя"), а список рассылки -- никогда.
> Предлагаю всё-таки не лоамться и согласиться на рабочее место/сервер с 
> пояснениями, что имеется в виду и примерами, какие темы подходят.
Ну, фактически это так и есть, просто я хотел, чтобы три категории в
группе выглядели замещающими друг друга и не включали в название такие
частности, как тип компьютера или профессию исполнителя.
> > * Для сообщества (чуть не забыл! у нас же проект основан на Сизифе! И
> >   вот категория для разработчиком всех мастей, от программистов до
> >   deployment manager-ов, сюда же всякие FR и прочее)
> Это правильно. 
> 
> Итого, получается:
> 
> Область применения
> 
> * Рабочее место
> * Сервер
> * Сообщество
	Ну я же говорил: поставленные рядом, эти категории кажутся
вполне пересекающимися :(. Предлагаю вернуться к моим.
> Способ изложения
> 
> * Инструкции
> * Индукции
> * Дедукции
	Тут я уже описал, почему против.
 
> * ALT (содержит ALT-специфику)
> 
> Итого 3 признака, 7 категорий -- мечта! 
	Мда. Вот было у нас золотое правило -- никогда не вырезать из
обсуждения документа строк. А то это обсуждение заходит на цикл.
Во-первых, мечта была не семь категорий изобрести, а дюжину или слегка
поболее, чтобы при формировании целевого издания (журнала, документации
к релизу, новостей или прочего) была свобода манёвра.
	Во вторых, пропал целый признак -- Уровень изложния. А это
немаловажно, по-моему (например, при подборе статей в стиле научпоп или,
наоборот, в профессиональную среду).
> Жду возражений, дополнений -- и в полиси. 

Мой вариант. Предполагается, что аргументы переписывать не надо. А вот в
полиси стоит включить по каждой категории предложение-два, объясняющее
её суть, так как категории достаточно общие.

  Уровень изложения
* Научно-популярный
* Пользовательский
* Профессиональный

  Тип документа
* Инструкции и презентации
* Аргументация(-ции?) и лекции
* Декларации и прокламации
* <catch-all>Публикации и инсинуации :)

  Тип решения
* Персональное
* Сервисное
* Общественное

  Специфичность
* ALT-specific
* UNIX/POSIX-specific

Итого 4/12. Мне кажется, не хватает ещё одного признака -- _области_
(всякое там мультимедия|программирование|кулинария|демагогия|etc.).
Только не пойму, как его исчерпывающе сформулировать -- пунктов этак не
более семи.

-- 
			George V Kouryachy (aka Fr. Br. George)
			mailto:george at altlinux_ru


Подробная информация о списке рассылки docs