L04 - Style in Technical Writing - 3 PDF

Style III: Style Guides 1  Action-based, Style II homework feedback specific heading Prepare virtual machines for cloning by using virt-sysprep Before cloning a virtual machine (VM), you have to prepare the guest system. The v...

Style III: Style Guides 1  Action-based, Style II homework feedback specific heading Prepare virtual machines for cloning by using virt-sysprep Before cloning a virtual machine (VM), you have to prepare the guest system. The virt-sysprep tool automatically removes selected guest configuration that should not be cloned with the VM. This configuration includes SSH keys, user accounts, and User-focused persistent MAC settings. abstract You can also use virt-sysprep to add specific configuration that you want to clone in the VM. To see what configuration you can add or remove, as well as the corresponding command-line arguments, run virt-sysprep --help. NOTE: The virt-sysprep tool does not currently support Windows guests. Distinct note Clear, parallel prereqs Prerequisites (passive OK) - The virt-sysprep package is installed on the host. - The VM is shut down. - You are the owner of the VM’s disk image. Procedure Procedure 1. (Optional) To create a backup and for verification, create a copy of the disk image. For more information, see… Optional step marked 2. Prepare the disk image: Action-based steps $ virt-sysprep -a /PATH/TO/THE/DISK/IMAGE.qcow2 Replace /PATH/TO/THE/DISK/IMAGE.qcow2 with the path to your image. Distinct values NOTE: By default, disk images are stored in /var/lib/libvirt/images/. (code, replaceables) Verification Verification 1. Compare the contents of the prepared image with the backup: $ virt-diff -a /PATH/TO/THE/OLD.qcow2 -A /PATH/TO/THE/NEW.qcow2 If the preparation process was successful, the command displays… Show output 3 Next steps Next steps After you have prepared the disk image, you can use virt-clone to clone the VM.  Topics Style I What is style? Goals of tech writing Style II Minimalism Topic-based authoring → Style III: Style guides ← What are style guides (for)? Major TW style guides 4 How to use style guides  Warm up Rewrite the following sentences as memes Use https://knowyourmeme.com/ as your style guide. - Press CTRL+ALT+DEL to open the task manager. (Yoda speak) - There are bugs. (X, X everywhere) - It works now. (Doge speak) - “I'm Slim Shady, yes, I'm the real Shady.” (Joseph Ducreux) - I’m sure I typed the password correctly. (Y U NO) 6 Image: https://knowyourmeme.com/memes/x-x-everywhere  English is “open source” 7 8  What is a style guide? A guide for writing style (duh) ○ More specific than grammar and dictionary Documentation for your documentation 9  Does this seem familiar? Follow these style rules when doing the homework: - Use simple language. - Avoid anthropomorphisms. - Avoid the passive voice. - Avoid using ‘will’. - Avoid phrasal verbs. - Avoid long sentences. - Avoid using words that are unclear and ambiguous. - Make the names of specific commands, utilities, pathways, and filenames visually distinct by using monospaced font. 10  What to focus on? Combining more words into less words ▸ Contractions Negative contractions ○ Have not vs. Haven’t ○ Can not vs. Can’t How does the use of either one impact the tone of what’s being said? Noun and verb contractions ○ “The browser is restarting” vs “The browser’s restarting” What are the possible pitfalls of this? 11  What to focus on? Combining more words into less words (cont.) ▸ Hyphens, en dashes, and em dashes First of all, what’s the difference? ○ - Hyphens are the shortest of these. ○ – En dashes are about the length of the “N” character. ○ — Em dashes are about the length of the “M” character. Why does that matter? Notes on using them ○ Why hyphens? Noun or modifier? User space vs. User-space [example]-specific ○ Ranges Monday–Friday vs. Monday to Friday 1–8 vs. 1 to 8 ○ Various specific words E.g. plug-in or plugin? 12 ○ What about em dashes?  What to focus on? Numbering conventions ▸ When to spell and when to use numerical digits? This is often specific to the individual organization ○ Some may prescribe a catch-all approach Example: Always use number or always spell ○ Some may have a varied approach Example: Spell out when the number is ten or less, use numbers for 11 and above. ▸ There may also be other specific numbering approaches depending on the type of work the company as a whole does, such as: Ordinal numbers (1st vs. 1st vs. First) Units of measurement Currency Dates 13  What to focus on? Capitalization ▸ Capitalization as a whole How are titles or section headings approached? ○ They Use Title Case vs. They use sentence case How are proper and common nouns defined or differentiated? ○ The Internet vs The internet ○ “Several chief operating officers …” ○ “Chief Operating Officer Bob Smith recommends …” Is it ever permissible to start a sentence in lower-case? ○ Specific terms (products, packages, etc) might always be entirely lower-case. Can capitalization be used for emphasis? If not, what are the other available options? ▸ Some more-specific scenarios Words that follow a colon: to capitalize or not? Words connected by a slash (e.g. “Use the on/off switch”) Hyphenated-words, when they begin a sentence how are they treated? 14  What to focus on? Abbreviations ▸ Acronyms How are industry or company-specific acronyms treated? ○ Should you spell them out with the acronym in parentheses on first occurrence? ○ Can you always default to commonly known acronyms? How is “commonly known” defined? HTML ▸ Other abbreviations Often times, specific abbreviations may be addressed independently in a style guide ○ Examples: e.g. (exempli gratia, “for example”), i.e. (id est, “that is”), vs/vs./v. (versus) 15  What to focus on? Abbreviations ▸ Some acronyms most people don’t realize are acronyms: ･ TASER Tom A. Smith’s Electric Rifle ･ LASER Light Amplification by Stimulated Emission of Radiation ･ CAPTCHA Completely Automated Public Turing test to tell Computers and Humans Apart ･ 16  What to focus on? Punctuation ▸ How do you present lists? ･ Bulleted? ･ Comma separated? ･ Does it matter? ▸ Where do you place periods and commas at the end of phrases in quotes? ･ Verify the instance is labelled “Server 1”. ･ Verify the instance is labelled “Server 1.” ▸ Are semicolons ever permissible? ･ Semicolons can often be replaced by commas and a coordinating conjunction (and, but, or, etc … ), but specific direction might differ based on the intended audience and tone. ▸ How are appositive phrases handled? ･ Essential appositive statements add information essential to the meaning of a sentence. ･ Non-essential appositive statements might add useful information, but do not impact the meaning of a sentence. 17 ･ Should these be in parentheses or commas? Do you treat them the same?  What to focus on? Punctuation (cont.) ▸ How are appositive phrases handled? First off, what are appositives? “The Recovery log that contains the most recent information is in the current_logs folder, which is generated automatically.” ○ Essential appositive statements (defining relative clauses) add information essential to the meaning of a sentence. ○ Non-essential appositive statements (non-defining relative clauses) might add useful information, but do not impact the meaning of a sentence. Should these be in parentheses, enclosed by commas, or something else? Do you treat them the same? 18  What to focus on? Highlighting ▸ What font or typeface do you use for different elements? ･ Product Names or just Product Names? You can use Red Hat Satellite for… ･ programs, files, commands, options, packages… Install the schmackage package to configure the schmogram program. ･ Emphasis or emphasis or emphasis or “emphasis” or EMPHASIS? Do “NOT” share the root password with non-privileged users. ･ User-replaced values 2. Add a new user: # useradd Replace with the name of the user. 19  What to focus on? Admonitions (notices) ▸ Note ･ IBM, Apple: Additional info ･ SUSE: Version differences ▸ Tip ･ SUSE: Additional info ▸ Important ･ Serious, essential information but not dangerous ▸ Warning ･ Apple: may cause bodily injury, damage, or loss of data ･ SUSE: Warn of security issues, potential loss of data, damage to hardware, or physical hazards. Warnings must always precede the action to which they apply. 20  Major Style Guides 21  EXERCISE 1 Find the guidance for the following features in various style guides: 1. “plug-in” / “plugin” / “plug in” 2. Non-exhaustive lists (“like”, “such as”, “etc.”) 3. Contractions (“don’t”, “isn’t”) and possessives (“user’s”) 4. “above”, “below”, “upper left” 5. Moving through content on a touchscreen https://documentation.suse.com/ https://support.apple.com/guide/ https://learn.microsoft.com/en-us/ style/ applestyleguide/ style-guide/ 22  What are style guides for? Unify tone of voice from many writers ○ Different organizations want to convey different tones in their documentation. Formal vs. informal vs. casual ○ Different audiences might be addressed in different tones or terms API documentation vs. an installation guide Help resolve difficult questions (such as excessive minimalism over a11y or UX) Provide rules and training materials for TWs 23  What are style guides NOT? Grammar books or vocabularies Markup guides Replacements for making stylistic choices Docs type templates Eternal, immovable entities 24  IBM Style - Relatively formal and conservative tone compared to the rest of the listed guides (with the exception of SUSE). - Crisp, no-nonsense style that’s not riveting to read but very easy to write. - Locked behind a paywall. 25  Microsoft Style Guide - The most casual tone of the listed style guides. - A friendly, approachable voice, ideal for communicating with casual IT users. - Communicates complex information in a simple, easily digestible way that doesn’t infantilize the audience. - The friendly voice can be difficult to replicate, making this guide more challenging to use than others. 26 https://learn.microsoft.com/en-us/style-guide/welcome/  Google Developer Documentation Style Guide - Friendly tone, less up-close-and-personal than Microsoft Style Guide. - Aimed at developers but offers a great foundation for tech writers across all knowledge levels. - Encourages writers to break the rules to achieve better content. 27 https://developers.google.com/style  Apple Style Guide - Less focused on technical writing than the rest of the listed guides. - A great resource for writing bias-free, inclusive content. - The guide has a confusing layout and is difficult to navigate. 28 https://support.apple.com/guide/applestyleguide/welcome/web  SUSE Documentation Style Guide - Extremely formal tone focused on professional appearance. - Provides less examples for its rules than other listed guides. - Very vague instructions regarding inclusivity and bias-free content creation. This puts non-native speakers at a disadvantage. 29 https://documentation.suse.com/style/current/  Microsoft Style IBM Style Edit or change your background during a Editing your background during a meeting meeting You can change your background while you are in To change your background during a meeting, a meeting. follow these steps: 1. In the meeting window, select More actions 1. In the meeting window, select More actions from the top of the screen > Background from the top of the screen > Background effects. effects. 2. Select one of the following options: 2. You can do the following: ○ Blur your background by selecting Blur. ○ Blur your background while everything around you is concealed. 30 https://support.microsoft.com/en-gb/office/customize-your-background-during-a-microsoft-teams-free-meeting-715a3e57-a0f1-44ee-ba9f-c9030888f0d3  EXERCISE 2 Read the three excerpts, each written according to a different style guide Configuring the RMT server Turn on device encryption How to download and install System Use this procedure to configure the Repository Mirroring Encryption helps protect the data on your device so it Use a web browser for older versions Tool (RMT). can only be accessed by people who have Requirements These older System versions are available as disk images authorization. If device encryption isn't available on System 15 is installed and up to date. your device, you might be able to turn on standard that you can download using your web browser. To get the You have a Customer Center account and organization BitLocker encryption instead. installer from the disk image, you must use a device that is compatible with that System. credentials. Turn on device encryption 1. Use these links to download a System disk image (.dmg) Procedure 1: Configuring the RMT server file. If these links don't work as expected, try again using a 1. Install RMT on System 15: 1. Sign in to the system with an administrator account browser, which is in your Applications folder. # zypper in rmt-server (you may have to sign out and back in to switch (list of links) 2. Start the rmt module in YaST: accounts). For more info, see Create a local or 2. Double-click the.dmg file to open it and see the package # yast2 rmt administrator account. (.pkg) file within. 3. Enter your Organization Credentials, then select Next. 3. Double-click the.pkg file, then follow the onscreen 2. Select Start > Settings > Privacy & security > instructions to install the System installer into your 💡To find your organization credentials, log in to the Device encryption. If Device encryption doesn't Applications folder. Customer Center, select your organization from My appear, it isn't available. You may be able to use 4. Open your Applications folder and double-click the Organizations, and click Proxies. Your organization's standard BitLocker encryption instead. Open Device System installer, named Install [Version Name]. Follow the onscreen installation instructions. Mirroring credentials are in the top right corner. encryption in Settings. 31  Internal style guides Supplement a more general parent guide Provide additional guidance in areas not covered by parent Specify divergences from the guidance of the parent Contain more specific examples and scenarios Therefore, override the more general guidance Provide consistency in your specific scenarios 32  Hierarchy of resources Most specific Specific Most general 33  Summary Style III: Style guides Docs for your docs Provide guidance for: ○ Tone ○ Minimalism ○ Numbers ○ Capitalization ○ Abbreviations Technical writers do ○ Punctuation not guess. If you’re not ○ Highlighting sure how to write something, look it up. Specific → General 34  Prerequisites for next class (26th March) Sign up for a GitHub account. Add ssh keys to your Github account. Install Git Set an email address in Git 35  HOMEWORK Homework assignment [Gdoc here] 36 Source: Image attribution: unsplash.com/@sigmund