From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Date: Tue, 6 Apr 2004 16:18:21 +0400 From: Kirill Maslinsky To: ALT Devel discussion list Message-ID: <20040406121821.GE2531@susanin.localdomain> Mail-Followup-To: ALT Devel discussion list Mime-Version: 1.0 Content-Type: text/plain; charset=koi8-r Content-Disposition: inline Content-Transfer-Encoding: 8bit User-Agent: Mutt/1.4.1i Organization: ALT Linux Team (Docs) Subject: [devel] =?koi8-r?b?0M/MydPJIMTM0SDP0MnTwc7JyiDQwcvF1M/XOiDawSDJ?= =?koi8-r?b?INDSz9TJ1w==?= X-BeenThere: devel@altlinux.ru X-Mailman-Version: 2.1.4 Precedence: list Reply-To: ALT Devel discussion list List-Id: ALT Devel discussion list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 06 Apr 2004 12:13:48 -0000 Archived-At: List-Archive: List-Post: Добрый день! Составляя справочный раздел документации на основе описаний пакетов, я обнаружил ужасный разнобой в терминологии, информативности и оформлении, а также огромное количество банальных опечаток, не говоря уже о размашистости стиля и жаргонности отдельных описаний. Отчетливо видно отсутствие какого-либо регулирующего полиси относительно словесных описаний, которыми сопровождаются пакеты. Причем описание пакета -- это первая и весьма существенная документация, на основании которой удобно было бы судить о необходимости установки этого пакета на свою машину и т. п. На мой взгляд, стоило бы следить за такими вещами: - орфография/пунктуация - единообразие терминов ("среда KDE"/"окружение KDE"; "UTF-8"/"utf8" etc.) - информативность: если в пакете собрано несколько утилит: перечислять их с кратким пояснением, если пакет предоставляет часть какой-то более общей функциональности или сопровождается отдельным пакетом с документацией/плагинами -- упоминать их в описании. (Пока больше точных требований сформулировать не могу, однако чем информативнее, тем лучше.) - стиль/удобопонятность: изгонятьс сугубо жаргонные выражения, и стараться писать так, чтобы из описания совершенно не знакомый с областью человек мог понять, для чего нужен данный пакет и нужен ли он ему. Возможно, некоторые из этих задач можно автоматизировать? (хотя бы ispell) Возможно, стоит отдавать все описания на просмотр централизованному редактору (перед принятеим в репозиторий)? Ваши соображения? -- Kirill Maslinsky ALT Linux Team * Documentation Project