𝔖 Scriptorium
✦   LIBER   ✦

πŸ“

Technical Writing for Software Developers

✍ Scribed by Chris Chinchilla


Publisher
Packt Publishing Pvt. Ltd.
Year
2024
Tongue
English
Leaves
321
Category
Library

⬇  Acquire This Volume

No coin nor oath required. For personal study only.

✦ Synopsis


Effective documentation is key to the success of products in remote software development teams, facilitating clear instructions that benefit the entire development team. Technical Writing for Software Developers lays a solid foundation of essential grammar, providing language tips and explaining how precise writing enhances documentation, and walks you through the fundamental types and styles of documentation. Starting with an exploration of the current state of the tech writing industry and its significance in both the software and hardware realms, you'll master the building blocks of technical writing, exploring tooling choices and style guides, and create dynamic multimedia-laden documentation. This book equips you with valuable insights into the writing and feedback process to ensure continuous improvement. Additionally, you'll take a peek at the emerging trends and technologies, including AI tools, shaping the future of technical writing. By the end of this technical writing book, you'll have developed the expertise you need to tackle documentation requests effectively, armed with the knowledge of the best approach for documenting any topic, encompassing text, media elements, structure, and appropriate tools. The skills acquired will enable you to achieve seamless teamwork, enhanced project efficiency, and successful software development.

✦ Table of Contents


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


πŸ“œ SIMILAR VOLUMES


Technical Writing for Software Developer
✍ Chris Chinchilla πŸ“‚ Library πŸ“… 2024 πŸ› Packt Publishing 🌐 English

Elevate your software development process with expert technical writing skills, fostering clarity, collaboration, and successful product outcomes Key Features β€’ Optimize documentation workflows with collaborative version-controlled "docs-as-code" tooling options β€’ Engage with interactive learni

Modern Technical Writing: An Introductio
✍ Andrew Etter πŸ“‚ Library πŸ“… 2016 🌐 English

<span>This slender volume provides the foundational knowledge to start creating and publishing great software documentation. Written by the lead technical writer at one of Silicon Valley's most exciting companies, Modern Technical Writing is a set of guiding principles and thoughtful recommendations