~ubuntu-core-doc/ubuntu-docs/maverick

<para>intro; terminology may seem tedius to learn, but if you want to avoid problems and make your writing clear and understandable to your audience, then you will want to learn them.</para>

<para>parts of a sentence</para>

</listitem>

<title>Subject and Predicate</title>

A sentence has two main parts; a subject and a predicate. The subject is the person or thing that you are talking about. The predicate is what you are saying about the subject. Without a subject and predicate, there is no sentence.

</formalpara>

</listitem>

<title>Clauses</title>

Stuff about main and subordinate (independent and dependent clauses), what they are, how to distinguish between the two types, and so on and so forth.

</formalpara>

</listitem>

<title>Run-on Sentences</title>

Do not use run-on sentences. Run-on sentences are actually two main clauses run together into one sentence and separated by a comma. You can correct a run-on sentence in more than one way.

</formalpara>

<tbody>

<row>

<entry><emphasis role="strong">Wrong</emphasis></entry>

<entry>There are also quite a few terminal-based editors available in Ubuntu, popular ones include VIM and Emacs </entry>

</row>

<row>

<entry><emphasis role="strong">Correct</emphasis></entry>

<entry>There are also quite a few terminal-based editors available in Ubuntu. Popular ones include VIM and Emacs.</entry>

</row>

<row>

<entry><emphasis role="strong">Correct</emphasis></entry>

<entry>There are also quite a few terminal-based editors available in Ubuntu; popular ones include VIM and Emacs.</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</listitem>

<para>one topic per paragraph</para>

</listitem>

</orderedlist>

</sect1>

<title>Punctuation</title>

<para>Much of this section may be obvious to most people, but it's important to clarify punctuation conventions to ensure that they are applied consistently across all documents. In addition, limits on the use of certain punctuation marks are imposed in order to ease document translation.</para>

<sect2>

<title>Apostrophe</title>

<para>The apostrophe is normally used in forming contractions, but in technical documents which will be translated into languages other than English, try to avoid contractions.</para>

<tbody>

<row>

<entry>can't, won't, doesn't</entry>

</row>

<row>

<entry>cannot, will not, does not</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</listitem>

<para>Avoid using the apostrophe to indicate possession because it can cause problems when your text is being translated into a different language. Instead, rework the sentence so that an apostrophe is not needed.</para>

<tbody>

<row>

<entry>The file's purpose is to store names and addresses.</entry>

</row>

<row>

<entry>The purpose of the file is to store names and addresses.</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</listitem>

<para>Do not use the apostrophe to form plurals of acronyms.</para>

100

101

102

103

104

<tbody>

105

<row>

106

107

108

</row>

109

<row>

110

111

112

</row>

113

</tbody>

114

</tgroup>

115

</informaltable>

116

</listitem>

117

118

<para>The apostrophe can be used to form plurals in certain cases where the lack of an apostrophe may cause confusion. For example, "1's and 0's"</para>

119

</listitem>

120

</orderedlist>

121

</sect2>

122

<sect2>

123

<title>Colon</title>

124

125

126

<para>You can use a colon after the words "following" or "follows." For example, "Docteam members need to install the following packages: <application>docbook</application>, <application>docbook-xsl</application>, and <application>subversion</application>."</para>

127

</listitem>

128

129

<para>Make sure that text preceding the colon is a complete sentence or a noun phrase. In the example below, a colon is not needed after "download"</para>

130

131

132

133

134

<tbody>

135

<row>

136

137

<entry>Before you try to install a web server, download: apache2, apache2-common, and apache2-doc.</entry>

138

</row>

139

<row>

140

141

<entry>Before you try to install a web server, download apache2, apache2-common, and apache2-doc.</entry>

142

</row>

143

</tbody>

144

</tgroup>

145

</informaltable>

146

</listitem>

147

148

<para>Use a colon after introductory text. For example, "You have only one option: Restart the computer."</para>

149

</listitem>

150

151

<para>Do not use a colon in headings, or at the end of a procedure heading.</para>

152

</listitem>

153

154

<para>Do not use a colon in a list that is introduced by "are" or "include."</para>

155

156

157

158

159

<tbody>

160

<row>

161

162

<entry>The functions available in the calculator application include: addition, subtraction, multiplication, and addition.</entry>

163

</row>

164

<row>

165

166

<entry>The functions available in the calculator application include addition, subtraction, multiplication, and addition.</entry>

167

</row>

168

</tbody>

169

</tgroup>

170

</informaltable>

171

</listitem>

172

</orderedlist>

173

</sect2>

174

<sect2>

175

<title>Comma</title>

176

<para>The rules for comma use in normal prose are numerous and complicated. However, in a technical document intended for translation, sentences will tend to be shorter and simpler than in normal prose. As a result, comma use will also tend to be limited and therefore only some of the major points are covered here.</para>

177

178

179

<para>Use the series comma. The series comma is the comma before the "and" in a list of three or more words or phrases.</para>

180

181

182

183

184

<tbody>

185

<row>

186

187

<entry>The functions available in the calculator application include addition, subtraction, multiplication and division.</entry>

188

</row>

189

<row>

190

191

<entry>The functions available in the calculator application include addition, subtraction, multiplication, and division.</entry>

192

</row>

193

</tbody>

194

</tgroup>

195

</informaltable>

196

</listitem>

197

198

<para>Use a comma to set off "for example" and similar words and phrases such as "namely" and "that is" For example, you can find many examples of this type of comma use in the style guide.</para>

199

</listitem>

200

201

<para>Use the comma after introductory phrases and clauses.</para>

202

203

204

205

206

<tbody>

207

<row>

208

<entry><emphasis role="strong">Example</emphasis></entry>

209

<entry>To open your browser, click on the Firefox icon.</entry>

210

</row>

211

<row>

212

<entry><emphasis role="strong">Example</emphasis></entry>

213

<entry>A few minutes after starting your computer, the login screen will appear</entry>

214

</row>

215

</tbody>

216

</tgroup>

217

</informaltable>

218

</listitem>

219

</orderedlist>

220

</sect2>

221

<sect2>

222

<title>Hyphen</title>

223

224

225

<para>Use a hyphen in compound modifiers preceeding a noun. Example: "Evolution is an end-user application."</para>

226

</listitem>

227

228

<para>Use a hyphen in spelled-out fractions, unless the fraction is at the start of a sentence. Example: "Well-written documentation is one-half of a successful software application."</para>

229

</listitem>

230

231

<para>Use a hyphen in compound words formed with "better", "best", and "well", unless they are already modified. Example: "Subversion is a well-known version control system. It has very well written documentation."</para>

232

</listitem>

233

</orderedlist>

234

</sect2>

235

<sect2>

236

<title>Parentheses</title>

237

238

239

<para>Use parentheses around abbreviations and acronyms that you will use later. Example: "The Ubuntu Documentation Project (UDP) is an important piece of the Ubuntu Linux distribution." </para>

240

</listitem>

241

242

<para>Do not use parentheses to set off an explanation or an aside. For example, do not write a sentence (like this one) that uses parentheses in this manner.</para>

243

</listitem>

244

</orderedlist>

245

</sect2>

246

<sect2>

247

<title>Period</title>

248

249

250

<para>Use a period to end sentences.</para>

251

</listitem>

252

253

<para>End abbreviations with a period. (eg. abbrev.)</para>

254

</listitem>

255

256

<para>Use a period at the end of each step in a procedure.</para>

257

</listitem>

258

259

<para>In lists, use a period only if the list items are complete sentences.</para>

260

</listitem>

261

</orderedlist>

262

</sect2>

263

<sect2>

264

<title>Quotation Marks</title>

265

266

267

<para>Use quotation marks around material that is repeated verbatim from another source, when the length of the copied material is such that it can be included "inline" with the paragraph.</para>

268

</listitem>

269

270

<para>Use quotation marks around letters, words or phrases that you want to emphasise without using italics or bold text.</para>

271

</listitem>

272

</orderedlist>

273

</sect2>

274

<sect2>

275

<title>Semicolon</title>

276

<para>The semicolon is frequently misused, so it's best to avoid it. A sentence with a semicolon can usually be split into two or more sentences. Splitting the sentence will make it easier to read and translate. </para>

277

</sect2>

278

</sect1>

279

280

<title>Spelling</title>

281

<formalpara><title>American English</title>

282

<para>Use standard American English spelling in all Ubuntu English language documents.</para>

283

</formalpara>

284

<formalpara><title>Dictionary (for spelling only)</title>

285

<para>There is a great deal of agreement among American English dictionaries when it comes to spelling, so for the purposes of Ubuntu technical documents, you can use any American English dictionary that is convenient. You can use the built-in spellchecker of whatever editor you are using, provided that it is set to American English. Places where there are conflicts (such as "email" versus "e-mail") are handled by the word list (see <xref linkend="styleguide-wordlist"/>). If you find a spelling conflict that is not in the word list, then please let us know what the word is along with your recommendation for the version to use. There is a list of online and printed dictionaries in the Reference Materials section.</para>

286

</formalpara>

287

<formalpara><title>Compound Words</title>

288

<para>In technical documentation, two-word compounds tend to get converted over time, first into hyphenated compounds, and then into single word compounds. For example, "on line" became "on-line", and is now gradually becoming "online". In general, use the one-word compound for Ubuntu documentation. However, there are several exceptions to this rule. If you are not sure of a particular word, then check the word list. See <xref linkend="styleguide-wordlist"/></para>

289

</formalpara>

290

</sect1>

291

</chapter>

292

Older »