From owner-freebsd-questions@FreeBSD.ORG  Thu Aug  7 04:48:41 2014
Return-Path: <owner-freebsd-questions@FreeBSD.ORG>
Delivered-To: freebsd-questions@freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115])
 (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits))
 (No client certificate requested)
 by hub.freebsd.org (Postfix) with ESMTPS id E68613A7
 for <freebsd-questions@freebsd.org>; Thu,  7 Aug 2014 04:48:41 +0000 (UTC)
Received: from wonkity.com (wonkity.com [67.158.26.137])
 (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
 (Client CN "wonkity.com", Issuer "wonkity.com" (not verified))
 by mx1.freebsd.org (Postfix) with ESMTPS id 95A0E2D3A
 for <freebsd-questions@freebsd.org>; Thu,  7 Aug 2014 04:48:41 +0000 (UTC)
Received: from wonkity.com (localhost [127.0.0.1])
 by wonkity.com (8.14.9/8.14.9) with ESMTP id s774mUqs050420
 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO);
 Wed, 6 Aug 2014 22:48:31 -0600 (MDT)
 (envelope-from wblock@wonkity.com)
Received: from localhost (wblock@localhost)
 by wonkity.com (8.14.9/8.14.9/Submit) with ESMTP id s774mU4n050405;
 Wed, 6 Aug 2014 22:48:30 -0600 (MDT)
 (envelope-from wblock@wonkity.com)
Date: Wed, 6 Aug 2014 22:48:30 -0600 (MDT)
From: Warren Block <wblock@wonkity.com>
To: Paul Kraus <paul@kraus-haus.org>
Subject: Re: Documentation WAS: pkg question ....
In-Reply-To: <10FF0A4F-F96E-4A68-BA25-56B57AFD4B2E@kraus-haus.org>
Message-ID: <alpine.BSF.2.11.1408062223080.94639@wonkity.com>
References: <53E0D2B7.9060402@hiwaay.net>
 <20140805131910.GA72939@slackbox.erewhon.home> <53E0E281.9030306@hiwaay.net>
 <20140805225107.ccf9944a.freebsd@edvax.de>
 <10FF0A4F-F96E-4A68-BA25-56B57AFD4B2E@kraus-haus.org>
User-Agent: Alpine 2.11 (BSF 23 2013-08-11)
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed
X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3
 (wonkity.com [127.0.0.1]); Wed, 06 Aug 2014 22:48:31 -0600 (MDT)
Cc: Polytropon <freebsd@edvax.de>,
 FreeBSD Questions !!!! <freebsd-questions@freebsd.org>
X-BeenThere: freebsd-questions@freebsd.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: User questions <freebsd-questions.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/options/freebsd-questions>, 
 <mailto:freebsd-questions-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-questions/>
List-Post: <mailto:freebsd-questions@freebsd.org>
List-Help: <mailto:freebsd-questions-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-questions>, 
 <mailto:freebsd-questions-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Thu, 07 Aug 2014 04:48:42 -0000

On Wed, 6 Aug 2014, Paul Kraus wrote:

> I understand that developers want to develop and not write manuals.

Documentation should be seen as part of developing.  It is not an 
optional extra.  A program without documents is incomplete.

Documentation does not have to be perfect, any more than the program 
itself.  But it should answer the basic questions:

What is this?
What are the requirements?
How is it used?

In that last part: good, useful examples can make the difference between 
a successful application and one that is abandoned because people can't 
figure out how make it work.

Finally, FreeBSD developers and users should be aware that the FreeBSD 
documentation team can provide assistance with creating man pages or 
DocBook documentation like the Handbook.  People interested in that help 
can post on the freebsd-doc mailing list.