Learning on the Go: Engineering Efficiency with Concise Documentation
April 15, 2019 / Global
Uber’s Learning on the Go program shares coding tips and useful work practices on posters throughout our offices. These tips come from the Uber engineering community’s everyday experience. We will periodically share them with the engineering community at large on the Uber Eng blog.
Technical documentation of products or services built by engineers helps onboard new users, spread information about how services work, and translate technical jargon into comprehensible prose. Some technology companies, including Uber, employ dedicated technical writers to partner with engineers and drive forward documentation efforts. However, when no technical writers are available, technical documentation is often written by engineers and is an essential part of the development workflow.
When writing technical documentation, keeping things concise can be challenging. Here are some tips that can help:
|
1. Practice reader empathy.
Know your audience. Write with them in mind to address their pain points, and provide them with accurate information. |
2. Avoid roundabout and wordy expressions.
? “Our website has made available many of the things you can use for making a decision on the best storage solution.” ? “Our website provides resources for determining the best storage solution.” By reducing wordiness, you save readers’ time and add clarity to your writing. |
|
3. Take reading time into account.
Longer doesn’t always mean better. Keep document length in mind! A TL;DR or overview section at the top of a long doc can also help readers find the information they need more quickly. |
Interested in working within an environment in which engineers are encouraged to share best practices? Consider applying for a role at Uber!
Shannon Brown
Shannon Brown is a technical writer at Uber and recent graduate from Wellesley College. In her spare time, she enjoys eating dessert, exploring the outdoors, and taking photographs.
Posted by Shannon Brown
Related articles
How LedgerStore Supports Trillions of Indexes at Uber
April 4 / Global
Most popular
Uber Health and Findhelp support patients beyond the four walls of a medical office
Stopping Uber Fraudsters Through Risk Challenges
Scaling AI/ML Infrastructure at Uber
Information for driving during the week of Super Bowl LVIII
Products
Company
