466274874 · cryptotaxi247/netdata-1

@@ -226,7 +226,7 @@ Use active voice instead of passive voice, because active voice is more concise

226 When using voice, the subject of the sentence is performing the action. In passive voice, the subject is being acted

227 upon. A famous example of passive voice is the phrase "mistakes were made."

228

229 -```

229 +```plain

230 # Not recommended (passive)

231 When an alarm is triggered by a metric, a notification is sent by Netdata...

232

@@ -236,7 +236,7 @@ When a metric triggers an alarm, Netdata sends a notification...

236

237 ### Standard American spelling

238

239 -While the Netdata team is mostly *not* American, we still aspire to use American spelling whenever possible, as it is

239 +While the Netdata team is mostly _not_ American, we still aspire to use American spelling whenever possible, as it is

240 more commonly used within the monitoring industry.

241

242 ### Clause order

@@ -244,7 +244,7 @@ more commonly used within the monitoring industry.

244 If you want to instruct your reader to take some action in a particular circumstance, such as optional steps, the

245 beginning of the sentence should indicate that circumstance.

246

247 -```

247 +```markup

248 # Not recommended

249 Read the reference guide if you'd like to learn more about custom dashboards.

250

@@ -253,14 +253,14 @@ If you'd like to learn more about custom dashboards, read the reference guide.

253 ```

254

255 By placing the circumstance at the beginning of the sentence, those who don't want to follow can stop reading and move

256 -on. Those who *do* want to read it are less likely to skip over the sentence.

256 +on. Those who _do_ want to read it are less likely to skip over the sentence.

257

258 ### Oxford comma

259

260 The Oxford comma is the comma used after the second-to-last item in a list of three or more items. It appears just

261 before "and" or "or."

262

263 -```

263 +```markup

264 # Not recommended

265 Netdata can monitor RAM, disk I/O, MySQL queries per second and lm-sensors.

266

@@ -268,6 +268,30 @@ Netdata can monitor RAM, disk I/O, MySQL queries per second and lm-sensors.

268 Netdata can monitor RAM, disk I/O, MySQL queries per second, and lm-sensors.

269 ```

270

271 +### Abbreviations (acronyms and initialisms)

272 +

273 +Use abbreviations (including [acronyms and initialisms](https://www.dictionary.com/e/acronym-vs-abbreviation/)) in

274 +documentation when one exists, when it's widely-accepted within the monitoring/sysadmin community, and when it improves

275 +the readability of a document.

276 +

277 +When introducing an abbreviation to a document for the first time, give the reader both the spelled-out version and the

278 +shortened version at the same time. For example:

279 +

280 +```markup

281 +You can use Netdata to monitor Extended Berkeley Packet Filter (eBPF) metrics in real-time.

282 +```

283 +

284 +After you define an abbreviation, don't switch back and forth—use only the abbreviation for the rest of the document.

285 +

286 +You can also use abbreviations in a document's title to keep the title short and relevant. If you do this, you should

287 +still introduce the spelled-out name alongside the abbreviation as soon as possible.

288 +

289 +```markup

290 +# Monitoring HDFS with Netdata

291 +

292 +You can now use Netdata to collect real-time metrics from your Hadoop Distributed File System (HDFS).

293 +```

294 +

295 ## Markdown syntax

296

297 The Netdata documentation uses the Markdown syntax for styling and formatting. If you're not familiar with how it works,

@@ -293,11 +317,9 @@ Click on the **Sign in** button.

317 !!! note Whenever possible, avoid using directional language to orient readers, because not every reader can use

318 instructions like "look at the top-left corner" to find their way around an interface.

319

296 -```

320 If you feel that you must use directional language, perhaps use an [image](#images) (with proper alt text) instead.

321

322 We're also working to establish standards for how we refer to certain elements of the Netdata's web interface. We'll include that in this style guide as soon as it's complete.

300 -```

323

324 ### Language-specific syntax highlighting in code blocks

325

@@ -313,7 +335,7 @@ no language is specified, the Highlight extension doesn't apply syntax highlight

335 Include the language directly after the three backticks (```` ``` ````) that start the code block. For highlighting C

336 code, for example:

337

316 -````

338 +````c

339 ```c

340 inline char *health_stock_config_dir(void) {

341 char buffer[FILENAME_MAX + 1];

Add acronyms to style guide (#8313)