Technical Writing for Software Developers

Technical Writing for Software Developers
Contributors
About the author
About the reviewers
Preface
   Welcome, wordsmiths!
   What is technical writing?
   What technical writing doesn’t include?
      Technical writing isn’t copywriting
      Technical writing isn’t interface copy
      Technical writing isn’t blogging
      Technical writing isn’t tech journalism
      Technical writing isn’t marketing copy
   A technical writing definition
   Who am I?
   Who can learn from this book?
   A note on terminology
   State of the industry
   Who this book is for
   What this book covers
   Conventions used
   Get in touch
   Share Your Thoughts
   Download a PDF copy of this book
1
The Why, Who, and How of Tech Writing
   Why should you care about tech writing?
   What can documentarians accomplish?
      Marketing
      Product
      Sales
      Support
      Developer relations
      Engineering
      Machine readers
      Proofreading for accuracy and safety
      Content silos
      Writer in the middle
   Understanding who you are writing for
      Learning by example
      Don’t forget the end users and the end-end users
   Summary
2
Understanding Different Types of Documentation in Software Development
   Templates
   Getting started and onboarding
      A detailed overview of Getting Started
      Learning with an example
      Templates for a Getting Started guide
   Tutorials
      Expanding on the example
      Templates for tutorials
   Reference
      API documentation
      Architecture and design details
      Security and privacy details
   Technical blog posts
   Summary
3
Language and the Fundamental Mechanics of Explaining
   Common reasons for not writing confidently
      Not a native speaker
      Intentionally vague
      Marketing and product reasons
      Reducing cognitive load
      Inclusive language
   How to improve your writing
      Consistency
      Involving the user
      Keeping it short
      Removing unnecessary words
      Don’t show off – let the product speak for itself
      Don’t repeat yourself
   Inclusive language: in more detail
      Overly negative language
      Biased language
      Gender
      Out-of-date language
   Summary
4
Page Structure and How It Aids Reading
   Humans are not your only readers
   The principles of good layout
   A quick primer on the markup language of the web
   Thinking about pages semantically
      Lists
      Paragraph breaks
      Tables
      Admonitions
      Tabs
   An example of a well-structured page
   Creating documentation menus and navigation
      Following menu patterns
      Adding internal search
      Keeping links working
   Summary
5
The Technical Writing Process
   Scoping and requirements gathering
   What to document
   Research and product testing
   Drafting and re-drafting
   Feedback, testing, and maintenance
      Metrics and measuring success
   Summary
6
Selecting the Right Tools for Efficient Documentation Creation
   Topic-based documentation
   Docs as code
   Documentation in the browser
   Choosing toolchains and tools
   Why docs as code?
      Selecting and using a markup language
      Adding metadata to markup with YAML
      Making Markdown dynamic with MDX
   The key tools in docs as code
      Text editor
      Collaboration
      Rendering
   Helping less technical writers with headless CMS
   Analyzing documentation performance
      Analytics tools
      Sentiment
   Summary
7
Handling Other Content Types for Comprehensive Documentation
   We are more than technical writers
   Code examples
      Deciding on a consistent example
      Creating and organizing code examples
      Testing code examples
      Keeping an eye on prerequisites
   Screenshots, images, and charts
      Screenshots
      Adding other images
      Making images accessible
   Animated GIFs and videos
      What to make a video of
      What to show
      How to record
      Audio
      What to show
      Recording
   Interactive experiences
   More than final words
8
Collaborative Workflows with Automated Documentation Processes
   Striking the right balance
   What is a style guide?
      Developer-friendly style guides
      Choosing a type of tool to use
   Automating image generation
      Using test suites
      Automating other image types
   Automating video
      Converting terminal commands to video
      Other video automation options
   Automating code testing
   Other automation options
      Converting file formats
      Accessibility
   Summary
9
Opportunities to Enhance Documentation with AI Tools
   A brief history of AI
   Understanding AI and ML
   Recent advances in AI
      Text and code completion and improvement
      Generating documentation
      AI for audio and video
      Generating media
   New ways of interacting
   The principles of training and creating your own AI
   Writing for robots
   Summary
Index
   Why subscribe?
Other Books You May Enjoy
   Packt is searching for authors like you
   Share Your Thoughts
   Download a free PDF copy of this book