From owner-svn-doc-head@FreeBSD.ORG Mon Jun 17 20:16:01 2013 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id 0788D9BB; Mon, 17 Jun 2013 20:16:01 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id DE4521D38; Mon, 17 Jun 2013 20:16:00 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r5HKG0U2025804; Mon, 17 Jun 2013 20:16:00 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r5HKG0gj025803; Mon, 17 Jun 2013 20:16:00 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201306172016.r5HKG0gj025803@svn.freebsd.org> From: Warren Block Date: Mon, 17 Jun 2013 20:16:00 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r41937 - head/en_US.ISO8859-1/books/fdp-primer/writing-style X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 17 Jun 2013 20:16:01 -0000 Author: wblock Date: Mon Jun 17 20:16:00 2013 New Revision: 41937 URL: http://svnweb.freebsd.org/changeset/doc/41937 Log: Add some suggestions on writing style to the FDP. Reviewed by: dru,trhodes Modified: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Mon Jun 17 19:54:32 2013 (r41936) +++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Mon Jun 17 20:16:00 2013 (r41937) @@ -205,13 +205,68 @@ also define them the first time they appear in each chapter. - The first three uses of an acronym should be enclosed in + All acronyms should be enclosed in acronym tags, with a role attribute with the full term defined. This allows a link to the glossary to be created, and for mouseovers to be rendered with the fully expanded term. + + Be Formal + + Write in a formal style. Avoid addressing the reader + as you. For example, say + copy the file to /tmp + rather than you can copy the file to + /tmp. + + + + Be Confident + + Avoid weasel words like + should, might, + try, or could. These words + imply that the speaker is unsure of the facts, and + create doubt in the reader. + + + + Be Imperative + + Give instructions as an imperative command: not + you should do this, but merely + do this. + + + + Be Simple + + Avoid flowery or embellished speech, jokes, or colloquial + expressions. Write as simply and clearly as possible. Simple + text is easier to understand and makes the job of translation + easier. + + Keep explanations as short, simple, and clear as possible. + Avoid empty phrases like in order to, which + usually just means to. Avoid potentially + patronizing words like basically. Avoid Latin + terms like i.e. or cf., which + may be unknown outside of academic or scientific + groups. + + + + Use the <quote>Three C</quote> Approach + + Writing must be clear, + complete, and + concise. These goals can conflict with + each other. Good writing consists of a balance between + them. + + Indentation