[devel] полиси для описаний пакетов: за и против

[Maxim Tyurin]

Kirill Maslinsky <kirill на altlinux.ru> writes:

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

Словарь терминов давно пора составить. Для оЧЕпяток есть ispell :)
А стиль он у каждого свой и ИМХО исправлениям совсем плохо поддается.

>
> Отчетливо видно отсутствие какого-либо регулирующего полиси относительно
> словесных описаний, которыми сопровождаются пакеты.
>
> Причем описание пакета -- это первая и весьма существенная документация, 
> на основании которой удобно было бы судить о необходимости установки
> этого пакета на свою машину и т. п.
>
> На мой взгляд, стоило бы следить за такими вещами:
> 	- орфография/пунктуация
> 	- единообразие терминов ("среда KDE"/"окружение KDE";
> 	  "UTF-8"/"utf8" etc.)

И обязательно с кодировками описаний беспредел исправить, а то
apt-cache приходится пару раз через iconv прогонять 

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

Нудная это работа. Сомневаюсь что кто-то этим заняться захочет.

> Ваши соображения?

Давно пора :)
-- 

With Best Regards, Maxim Tyurin
JID:	MrKooll на jabber.pibhe.com