红帽技术写作风格指南
Red Hat Technical Writing Style Guide

原始链接: https://stylepedia.net/style/

该样式指南为技术写作提供了具体规则。始终使用“ IBM S/390”,“ SaaS”,“ Samba”和“ S Record”。使用“屏幕截图”作为一个单词。请参阅“屏幕保护程序”和“卷轴”作为两个单词。与其说产品或服务是“安全的”,不如说明特征或质量如何提供可信度和韧性,并在其存在的地方提供可验证的数据。在讨论安全性时,请使用预选赛来避免对安全性提出确定性或未经证实的主张。替换为“参考”或更精确的动词。最小化“ segfault”的使用。使用“ Selinux”进行安全增强的Linux。避免“发送”;改用“发射”或“问题”。 “设置”是名词/形容词,“设置”是动词。 “ SHA-1”和“ SHA-2”需要“无限期的文章”。正确使用“ Shadowman”。 “影子密码”和“影子实用程序”不是适当的名词。正确使用“共享名称”。使用“ Shebang”。避免使用“ shell”来描述在哪里输入命令;相反,请参阅“壳提示”。使用“必须”而不是“应该”来满足要求。使用“关闭”作为动词。将“登录”和“签名”写为形容词或名词,或两个单词作为动词。避免“技能集”;改用“技能”或“知识”。使用“ SLA”时,仅应将官方的SLA缺陷评级大写。不要使用“奴隶”;使用替代方案。将“智能卡”称为两个单词。指定袜子版本时,请使用“ socksv4”或“ socksv5”。请勿使用“软拷贝”;改用“在线”。将“声卡”写为两个单词。更改为命名用户的Linux命令是“ SU”。不要使用“小队”;改用“团队”或“组”。正确使用“ SR-IOV”。正确使用“ SSH”和“ SSL”。请参阅带有连字符的“独立”。使用“ startx”。该术语必须“直接”。

这个黑客新闻线程讨论了红帽技术写作风格指南,用户提供了赞美和批评。 一些用户赞扬该指南的全面性质和有用的例子。一个关键的讨论点是“最佳实践”和“惯例”在样式指南中的区别,一位用户主张优先考虑具有最高投资回报的编辑,并链接到他们开发的以前的样式指南,强调最佳实践。 其他人则辩论包含基本语法规则,其中一些人认为应该为技术作家提供知识。还提出了对指南中特定示例的担忧,包括措辞选择和使用“理智检查”等潜在有问题的术语。一些用户看到了AI驱动样式检查工具的潜力,但由于样式指南规则的复杂性,强调了有效实施它们的挑战。 最后,讨论涉及Red Hat的文档实践,包括获取知识库文章的访问,这是某些人的争论点。
相关文章

原文
S/390

Use the full description "IBM S/390". Do not use "s390", "S390", or any other variations.

SaaS
The correct abbreviation for "Software-as-a-Service". Refer also to PaaS.
Samba

Correct. Do not use "samba" or "SAMBA".

S-record

Correct. Do not use "s-record", "Record", "s-Record", or any other variations.

screenshot

n. Use this term, and write as one word. Do not use other terms or variations.

screen saver

n. Do not use "screensaver".

scrollbar

n. Do not use "scroll bar" or "scroll-bar".

secure

Instead of stating that a product or service is "secure", describe specifically how features or qualities provide trustworthiness and resilience, and provide verifiable data where it exists. When discussing security, use qualifiers to avoid making definitive or unsubstantiated claims about security.

Table 27.1. 

Original textImprovement
This [product or solution] is secure.This [product or solution] enables you to [do X, Y, and Z] to improve security, by ...
This [product or solution] is more secure.This [product or solution] is more secure through [describe the steps that are taken]; or This [product or solution] is more secure than [previous state, or competitor example with cited source].
see

For references within a document, and for cross-references to other resources, do not use “see”. Use “refer to”.

For descriptions of graphics, explanations of command outputs, and other similar cases, it is acceptable to use “see”. Alternatively, it might be more concise or precise to replace “see” with another verb in these cases. For example, instead of using "Click a server link to see the result details", you could use "Click a server link for the result details". Instead of using "As you can see, these expected Audit events have an AVC Audit record", you could use "As shown in the output, these expected Audit events have an AVC Audit record".

segmentation fault

n. Only use the abbreviation "segfault" if absolutely necessary, and never use it as a verb.

SELinux

Abbreviation of Security-Enhanced Linux. SELinux uses Linux Security Modules (LSM) in the Linux kernel to provide a range of minimum-privilege-required security policies. Do not use any other forms.

send out

Do not use. Instead, use "emit" or "issue".

server farm

Also referred to as a server cluster, computer farm, or ranch. A server farm is a group of networked servers that are housed in one location. A server farm streamlines internal processes by distributing the workload between the individual components of the farm and expedites computing processes by harnessing the power of multiple servers. The farms rely on load-balancing software that accomplishes such tasks as tracking demand for processing power from different machines, prioritizing the tasks, and scheduling and rescheduling them depending on priority and demand that users put on the network. When one server in the farm fails, another can step in as a backup.

server-side/server side
setup

Use "setup" as a noun or an adjective, and "set up" as a verb. For example:

  • Each setup provides different features.

  • You need to set up a user profile as part of the registration process.

  • Follow the setup instructions that are included with the hardware.

SHA-1, SHA-2

Pronounced "shä" and thus requires "an" as the indefinite article.

SHA stands for Secure Hash Algorithm; each is a cryptographic hash function. SHA2 variants are often specified by using their digest size, in bits, as the trailing number, instead of "2". Thus "SHA224", "SHA256", "SHA384", and "SHA512" are considered correct when referring to these specific hash functions.

Shadowman

Correct. Do not use "Shadow Man" or "ShadowMan". The Red Hat Shadowman logo is a trademark of Red Hat, Inc., registered in the United States and other countries.

shadow passwords

Not a proper noun, so capitalize "Shadow" at the beginning of a sentence only.

Shadow passwords are a method of improving system security by moving the encrypted passwords (normally found in /etc/passwd) to /etc/shadow, which is readable only by root. This option is available during installation and is part of the shadow utilities package.

shadow utilities

Not a proper noun, so capitalize "Shadow" at the beginning of a sentence only.

share name

Correct. Do not use "sharename" or "Sharename" unless you are quoting the output of commands, such as smbclient -L or similar.

shebang

n. Refers to the character sequence consisting of the number sign and exclamation point (#!) at the beginning of a script. Do not use hashbang or pound-bang or other variations.

shell

A "shell" is a software application, for example, /bin/bash or /bin/sh, which provides an interface to a computer. Do not use this term to describe where to type commands.

shell prompt

Refers to the character at the beginning of the command line, and indicates that the shell is ready to accept commands. Do not use "command prompt" or "shell".

For example, "If you enter your username and password correctly, then you log in and get a shell prompt."

should
Do not use if it is something the user must do. For example, "You should make a backup" is a suggestion, but "You must make a backup" is a requirement. Refer also to must.
shut down

v. Correct. Do not use "shut-down". Only use "shutdown" when referring to the /sbin/shutdown system command.

sign-in, sign in

Write hyphenated as an adjective or noun, or as two words as a verb.

  • adj., n. Hyphenated. For example, "the sign-in page".

  • v. Two words. For example, "to sign in by using your IAM user account ID".

In general, use "log in" when referring to Linux-based technologies and platforms. In some cases, a tool or platform might use "sign in" or other terms to describe starting a session by entering a username and password. In these cases, align to the terminology that is used in the user interface.

sign in to

v. Write as three words. For example, "to sign in to the system".

sign-on, sign on

Write hyphenated as an adjective or noun, or as two words as a verb.

In general, use "log in" when referring to Linux-based technologies and platforms. In some cases, a tool or platform might use "sign in" or other terms to describe starting a session by entering a username and password. In these cases, align to the terminology that is used in the user interface.

simply
since, as, because

Do not use "since" or "as" to mean "because"; it is ambiguous. Use "because" to refer to a reason. Use "since" or "as" to refer to the passage of time.

skill set, skills, knowledge

n. Avoid using "skill set" as much as possible; use "skills" or "knowledge" instead. Do not use "skill set" or "skill-set" as an adjective. Do not use "skill-set knowledge"; it is redundant. Refer to the following examples:

Example 27.1. Example Use of Term "Skillset" Versus "Skills"

Incorrect: Do you have the right skillset to be an RHCE?

Correct: Do you have the right skills to be an RHCE?

Example 27.2. Example Use of Term "Knowledge"

Incorrect: This course gives you the skill-set knowledge to complete your RHCT exam successfully.

Correct: This course gives you the knowledge to complete your RHCT exam successfully.

SLA

n. SLA stands for Service Level agreement. The phrase itself is not normally capitalized but official SLA defect ratings, such as Low, Moderate, and Critical, carry initial caps. This capitalization distinguishes the SLA-defined ratings from the severity of general issues and identifies them as requiring a predetermined response time and level of support according to agreements.

slave

Do not use. It diminishes the horror of the dehumanizing practice of slavery. Use another term such as "worker", "child", "helper", "replica", or "secondary (server, node, process, or other noun)".

smart card

adj., n. Always use the two-word form. Do not use "smart-card" or other variations. Do not capitalize unless it is part of a product name or other proper noun.

SOCKS

Correct. Do not use "socks". When specifying a SOCKS version, use "SOCKSv4" or "SOCKSv5".

softcopy

Do not use. Instead, use "online". For example, "To view the online documentation ...".

sound card

n. Do not use "soundcard" or "sound-card".

source

v. In addition to the generic use of this term as a noun and verb, in a programming and technical sense, it also means "Run the source command against the named file."

Source-Navigator™

Correct. Do not use "Source Navigator". Source-Navigator™ is a trademark of Red Hat.

space

Use when referring to white space, such as "Ensure that a space occurs between each command." Use "Spacebar" when referring to the keyboard key.

Spacebar

n. Use when referring to the keyboard key, such as "Press the Spacebar key to continue."

spec file

n. Use to refer to an RPM spec file. Do not use "specfile".

specific

When used as a modifier, put a hyphen before "specific", such as "MIP-specific", "Linux-specific", and "chip-specific".

spelled

Correct. It is the standard US English spelling. Do not use "spelt".

SQL

When referring to the ISO standard (ISO 9075 and its descendants), it is pronounced as an initialism: ĕs kyü ĕl. Consequently, it takes "an" as an indefinite article.

When referring to Microsoft's proprietary product, SQL Server, pronounce it as a word: "sequel". In this case, it takes "a" as an indefinite article.

Note: Oracle also pronounces its SQL-based products (such as PL/SQL) as "sequel".

More generally, avoid "SQL" as a generic marker if possible. When discussing MySQL, write "MySQL". When discussing Microsoft SQL Server, write "Microsoft SQL Server". When discussing PostgreSQL (which is pronounced pŏstgrĕs kyü ĕl), write "PostgreSQL".

squad (n.)

Do not use to refer to a group that is formed to accomplish a task. Use "team" or "group" instead.

SR-IOV

Correct. SR-IOV stands for Single Root I/O Virtualization. It is a virtualization specification for a PCIe device to appear to be multiple separate physical PCIe devices. Do not use SR/IOV.

SSH

Initialism for Secure Shell, a network protocol for data exchange with a secure channel. When referring to the protocol, do not use "ssh", "Ssh", or other variants. When referring to the command, use ssh.

Do not use as a verb.

Example 27.3.  Example Use of "SSH"

Incorrect: To begin, "ssh to the remote server".

Correct: "Use SSH to connect to the remote server", "Open an SSH connection", or something similar.

SSL

Initialism for Secure Sockets Layer, a protocol developed by Netscape for transmitting private documents over the internet. SSL uses a public key to encrypt data that is transferred over the SSL connection. Most web browsers support SSL, and many websites use the protocol to obtain confidential user information, such as credit card numbers. By convention, URLs that require an SSL connection start with https: instead of http:. SSL later evolved into Transport Layer Security (TLS).

stand-alone

adj. Hyphenate. Do not use "standalone".

Refers to something that is self-contained, or that does not require any other devices to function. For example, a smartphone is a stand-alone device because it does not require a computer, printer, modem, or other device. A printer, on the other hand, is not a stand-alone device because it requires a computer to feed it data.

StarOffice

A legacy Linux desktop suite. Do not use "Star", "Staroffice", or "Star Office".

start up

v. Do not use. Instead, use "start", "activate", or "invoke".

startx

Correct. Do not use StartX or other variants.

straightforward

adj., adv. Accepted references prescribe the use of the one-word form in all cases. Do not use "straight-forward".

su

Correct. The Linux command to change to a named user. Do not use SU (all caps).

subcommand

Correct. Do not use "sub-command" or refer to a subcommand as a "verb". A subcommand refers to a secondary or even a tertiary command that is used with a primary command. Not to be confused with options or arguments, subcommands operate on ever more focused objects or entities. For example:

hammer import organization --help

In this example, "hammer" is the main or primary command, and "import" and "organization" are subcommands. --help is an option.

subdirectory
submenu
subpackage

Correct. Do not use "sub-package".

This word has a specific, specialized meaning in Red Hat products. An RPM spec file can define more than one package: these additional packages are called "subpackages".

Any other use of this word is strongly discouraged.

Note: Subpackages are not the same as dependencies and should not be treated as such.

superuser

A synonym for the root user. More common in Solaris documentation than Linux. If and when used, this spelling is correct. Do not use "super user" or "super-user".

swap space

Correct. Do not use "swapspace". Capitalize at the beginning of a sentence only.

Sybase Adaptive Server Enterprise (ASE)

Use SAP Sybase Adaptive Server Enterprise (ASE) in the first instance. Subsequent entries can use the abbreviation "Sybase ASE". If discussing the high-availability version, use "Sybase ASE and High Availability".

SysV

Correct. Do not use Sys V or System V.

symmetric encryption

A type of encryption where the same key is used to encrypt and to decrypt the message. It differs from asymmetric (or public-key) encryption, which uses one key to encrypt a message and another to decrypt the message.

联系我们 contact @ memedata.com