From owner-svn-doc-all@FreeBSD.ORG Thu Jun 20 16:40:43 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 17267540; Thu, 20 Jun 2013 16:40:43 +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 07C0C15FA; Thu, 20 Jun 2013 16:40:43 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r5KGegnn092583; Thu, 20 Jun 2013 16:40:42 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r5KGegSU092582; Thu, 20 Jun 2013 16:40:42 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201306201640.r5KGegSU092582@svn.freebsd.org> From: Warren Block Date: Thu, 20 Jun 2013 16:40:42 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r41970 - 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-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 20 Jun 2013 16:40:43 -0000 Author: wblock Date: Thu Jun 20 16:40:42 2013 New Revision: 41970 URL: http://svnweb.freebsd.org/changeset/doc/41970 Log: Rearrange the Writing Style chapter. Move new tips to a new section, and organize them into clear, complete, and concise categories. 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 Thu Jun 20 16:39:11 2013 (r41969) +++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Thu Jun 20 16:40:42 2013 (r41970) @@ -34,7 +34,81 @@ Writing Style - In order to promote consistency between the myriad authors of + + Tips + + Technical documentation can be improved by consistent use of + several principes. Most of these can be classified into three + goals: be clear, + be complete, and + be concise. These goals can conflict with + each other. Good writing consists of a balance between + them. + + + Be Clear + + Clarity is extremely important. The reader may be a + novice, or reading the document in a second language. Strive + for simple, uncomplicated text that clearly explains the + concepts. + + Avoid flowery or embellished speech, jokes, or colloquial + expressions. Write as simply and clearly as possible. Simple + text is easier to understand and translate. + + 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. + + 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. + + 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. + + Similarly, give instructions as imperative commands: not + you should do this, but merely + do this. + + + + Be Complete + + Do not make assumptions about the reader's abilities or + skill level. Tell them what they need to know. Give links to + other documents to provide background information without + having to recreate it. Put yourself in the reader's place, + and answer the questions they will ask. + + + + Be Concise + + While features should be documented completely, sometimes + there is so much information that the reader cannot easily + find the specific detail needed. The balance between being + complete and being concise is a challenge. One approach is to + have an introduction, then a quick start + section that describes the most common situation, followed by + an in-depth reference section. + + + + + Guidelines + + To promote consistency between the myriad authors of the FreeBSD documentation, some guidelines have been drawn up for authors to follow. @@ -170,6 +244,7 @@ For more information about writing style, see Elements of Style, by William Strunk. + Style Guide @@ -212,61 +287,6 @@ 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 @@ -459,7 +479,7 @@ GB. Hardware compression …This list of words shows the correct spelling and capitalization when used in FreeBSD Documentation. If a word is - not on this list, ask about that word on the &a.doc;. + not on this list, ask about it on the &a.doc;. @@ -473,12 +493,12 @@ GB. Hardware compression … CD-ROM - CD-ROM]]> + CD-ROM]]> DoS (Denial of Service) - DoS]]> + DoS]]> @@ -523,7 +543,7 @@ GB. Hardware compression … &unix; - +