[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