GNU Essentials GNU Linux Manual of Style for Technical Content Creators 2020 Copyright (c) GNU Essentials ISBN: 978-1-71683-468-4 Manufactured in the United States of America You may distribute the GNU Linux Manual of Style and/or modify the GNU Linux Manual of Style under the following terms: Code GNU General Public License (http://www.gnu.org/licenses/gpl.html), version 3 or later Content Creative Commons Attribution License (http://creativecommons.org/licenses/by/4.0/), version 4.0 or later (Other content used in the book was this license, so this became the preferred license) Trademarks: Respecting the choice to trademark by others, we do not have trademark rules for GNU Essentials, FAQ Linux, R00T magazine or A-Z Technical Writing. Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries. Foreword About the Author Overview Dedication Revision History 1. Documentation Development Life Cycle 1.0 Basics of Technical Authoring...........................................................................................................11 1.1 Documentation Development Life Cycle............................................................................................11 1.2 Example: Get Started Guide..............................................................................................................29 Chapter 2. GNU Linux Style Guidelines 2.0 Headings...........................................................................................................................................35 2.1 Images.............................................................................................................................................. 36 2.2 Copy Code........................................................................................................................................38 2.3 General Content................................................................................................................................38 2.4 Capitalization.....................................................................................................................................45 2.5 Spelling............................................................................................................................................. 45 2.6 Dates................................................................................................................................................. 45 2.7 Lists................................................................................................................................................... 46 2.8 Numbers in text.................................................................................................................................46 2.9 Front Matter.......................................................................................................................................48 2.10 Back Matter.......................................................................................................................................48 2.11 Cross References..............................................................................................................................48 2.10 Table of Contents and Index.............................................................................................................48 2.11 Measurements...................................................................................................................................49 2.12 Versions............................................................................................................................................49 Chapter 3: Best Practices 3.0 Paths and Permissions..........................................................................................................................51 3.1 Dependencies........................................................................................................................................51 3.2 Links......................................................................................................................................................51 3.3 Code......................................................................................................................................................53 3.4 Audience and Tone................................................................................................................................60 3.5 Grammar................................................................................................................................................ 64 3.6 Punctuation............................................................................................................................................64 3.7 User (Normal User, Root User, End User).............................................................................................67 3.8 Naming (example: Pop OS! Greek translation)......................................................................................67 3.9 Communications and Contents..............................................................................................................68 Chapter 4. Developer Documentation Best Practices 4.0 Acronyms...............................................................................................................................................70 4.1 Internet of Things or IoT.........................................................................................................................71 4.2 Cultural issues.......................................................................................................................................72 4.3 Text Editors............................................................................................................................................73 4.4 Spacing.................................................................................................................................................. 74 4.5 Clear Communication.............................................................................................................................74 4.6 Multiple Operating Systems...................................................................................................................75 4.7 Website Images.....................................................................................................................................76 4.8 Infographics...........................................................................................................................................76 4.9 Key Commands ....................................................................................................................................77 4.10 FAQs or Troubleshooting Tips ............................................................................................................77 4.11 Command or brand 83 Chapter 5. Documentation Considerations 5.0 Management of Information...................................................................................................................79 5.1 Management of Information Plan...........................................................................................................79 5.2 Management of Information Plan Sample..............................................................................................79 5.3 Content Creator Toolbox........................................................................................................................80 5.4 Documentation Types............................................................................................................................81 5.5 Website Content....................................................................................................................................81 5.6 Accessibility...........................................................................................................................................81 5.7 Privacy and Privacy Template – Participant Testing..............................................................................82 5.8 Security.................................................................................................................................................. 85 Chapter 6. Legal and Licensing 6.0 General Trademark and Copyright information ......................................................................................87 6.1 Embargoed Content................................................................................................................................87 6.2 Free Content...........................................................................................................................................87 6.3 Non-Compete Agreements ....................................................................................................................87 6.4 Documentation Licensing.......................................................................................................................87 6.5 Debian Documentation Licensing (FREE)..............................................................................................88 6.6 RedHat Documentation Licensing (FREE)..............................................................................................89 6.7 Ubuntu Documentation Licensing (Copyright notice) .............................................................................89 Appendix Appendix A. man pages................................................................................................................................89