From owner-freebsd-doc@FreeBSD.ORG Sun Feb 2 18:59:00 2014 Return-Path: Delivered-To: freebsd-doc@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id ADC89AD8 for ; Sun, 2 Feb 2014 18:59:00 +0000 (UTC) Received: from wonkity.com (wonkity.com [67.158.26.137]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 63BFB13C3 for ; Sun, 2 Feb 2014 18:59:00 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.7/8.14.7) with ESMTP id s12Iww6l017322 for ; Sun, 2 Feb 2014 11:58:58 -0700 (MST) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.7/8.14.7/Submit) with ESMTP id s12IwwDC017319 for ; Sun, 2 Feb 2014 11:58:58 -0700 (MST) (envelope-from wblock@wonkity.com) Date: Sun, 2 Feb 2014 11:58:58 -0700 (MST) From: Warren Block To: freebsd-doc@FreeBSD.org Subject: RFC: Author information display in documents Message-ID: User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; format=flowed; charset=US-ASCII X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Sun, 02 Feb 2014 11:58:58 -0700 (MST) X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 02 Feb 2014 18:59:00 -0000 Based on a discussion on IRC, we'd like to ask for comments from people who have authored or contributed to documentation. At present, authors add their name and sometimes a description of their work like "Contributed by" or "Rewritten by". These author attributions are often quickly outdated as numerous other contributors fix problems and modify or add new content to the same section. There is potential for improving how this information is displayed. One possibility is auto-generating an Authors page, showing a list of authors and which portions of the document they have contributed. We have not yet considered technical aspects of generating this page, or the exact output format. However, it could be similar to a table of contents or index. As an initial mockup, consider this: Authors and Contributors Susan B. Anthony Contributed By: DHCP and Why You Should Care, page 12 ATM, the Silent Killer, page 54 Edited By: PPP for Dog Owners, page 38 John Smith Contributed By: Encrypting Disks, page 19 Reinstalling FreeBSD, page 20 Recovering from Backup, page 20 Edited By: When to Use Encryption, page 18 Rewritten By: Pitfalls of Encryption, page 18 The format of the list and contents would vary depending on the media. On the web, the titles would be links to the actual sections. In both cases, individual authors would not be shown at the top of the actual chapter or section in either HTML or PDF versions. The goal is to make the contributor information more accurate, more complete, and less distracting from content. We welcome comments and suggestions on this proposal.