StyleGuides / WritingStyleGuide

The official Red Hat guide to writing clear, concise, and consistent technical documentation.
Creative Commons Attribution Share Alike 4.0 International
71 stars 19 forks source link

Clarify terms related to creating/extracting and compressing/decompressing archives #549

Closed rclee33 closed 5 months ago

rclee33 commented 6 months ago

Suggested updates:

tar n., adj. The tape archive file format. Only use in reference to the file format, for example "a .tar file". See the Word Usage chapter of the IBM Style Guide.

v. Do not use to refer to the process of creating a .tar file. See the Word Usage chapter of the IBM Style Guide.

tarball n. In most cases, do not use “tarball” to refer to a compressed archive in the tar format. Use ".tar file".

In some limited cases, “tarball” might be introduced as a commonly used term for a compressed archive in the tar format. In such cases, briefly mentioning the term as an alternative name might be acceptable, but do not use “tarball” as the primary term to refer to compressed archives.

untar v. Do not use. See the Word Usage chapter of the IBM Style Guide.

unzip v. Do not use. See the Word Usage chapter of the IBM Style Guide.

zip v. Do not use. See the Word Usage chapter of the IBM Style Guide.

rclee33 commented 6 months ago

@julian-cable @daobrien @sffrench Please share your thoughts!

julian-cable commented 6 months ago

@rclee33 Based on our existing word usage entries, I suggest having a single entry for "tar" and giving the guidance by parts of speech within it. In this case it would be adj./noun versus v. The term "tar" should be defined only once.

rclee33 commented 6 months ago

@julian-cable Oh, yes -- that makes sense to me!

rclee33 commented 6 months ago

@julian-cable I updated the original issue to address your feedback.