API doc skills are in demand
Andrew Davis from Synergistech | synergistech@gmail.com | Presentation Slides
Andrew Davis recruits technical writers for software developers in the San Francisco area.
Application Programming Interface (API)
An API is a set of routines, protocols, and tools for building software that specify how software components should interact.
API Documentation
A technical communication deliverable, the documentation facilitates usage and implementation of the API.
API documentation vs. other forms of technical writing
SDK or API documentation is different in its greater technical complexity. API doc writers need to know what developers already know, what they need to know, and then how best to address those needs all without hand holding from the SMEs. Writers need to figure out the code, test it, make sense out of it, and document it.
Demand for this skill exceeds the supply. There is no proven on ramp to API tech writing and it’s really challenging to gain the required skills and experience you need.
Skills and abilities that open doors
Technology knowledge consistently beats writing, tools, and audience experience.
- Read code. Basic knowledge of a programming language like Python or Java. C, C++ and a front end language like Java Script are also helpful.
- Install products and set up a sandbox without help. A sandbox is an environment that testers can use to simulate the characteristics of the production environment and create simulated responses from APIs the application relies on.
- Master docs-like-code practices. A project focusing on best practices and lessons learned about applying software development techniques and tools to software documentation.
- Plug into developer’s communication channels. Examples are slack.com, giff.com, etc.
Traits and assets that keep them open
You don’t need to be a programmer, but you have to be unafraid to code. Your mission is to make your SMEs look good.
Team skills:
- Understand the team. Know their product, the audience, and write well without handholding, you will prosper.
- Optimize their content toolchain. Seek ways to produce content faster. Integrate content with the company’s source control tools like GitHub.
- Measure your productivity. If you can say I’ve fixed this number of bugs, or created this number of pages or topics, you will earn the respect of the SMEs.
- Get geekier. Dig deeper into the product and seek ways to evolve. Take pleasure in arcane knowledge.
Soft skills:
- Keep your word. Promise only what you can deliver.
- Listen actively. Echo back to developers their requests for clarity on what you hear. Be resourceful and ask well informed questions.
- Take initiative. If you can jump in and create content quickly your SMEs are going to be happy.
- Never stop learning. API doc is not a 9-5 job. Make this your life.
Location of the strongest demand for API doc jobs is in the USA
California offers the strongest demand in the country because founders and key engineers want to live here. Venture capitalists are set up here and the venture capitalist system works in this country.
USA is also the safest place to develop host core intellectual property because of the copyright laws. It’s only getting more valued and is unlikely to get off-shored soon.
Pay range for API doc writers
When companies find the right combination of skills, experience and the “I’ll make you look good” attitude, pay rates soar. You can find premium pay, excellent job security, and self directed career growth when you have API documentation skills and the experience to prove it.
- 1099-based contractor (/hr.): $75 – $115
- W2-based contractor (/hr.): $60 – $95
- Full time staff (/yr.): $120K – $155K
Contractor’s pay rate is lowered with a recruiter’s intermediation, but not for a staff role.
API doc skills are in demand —Getting there from here
Large companies with a team of writers where tasks are divided up may be more willing to take on a beginner level API doc writer.
Start-ups and smaller companies are the least likely to take on a writer with minimal API doc skills. These companies need to get the job done with fewer writers or just one writer with an army-of-one capability.
API documentation resources
- Markdown markdownguide.org
- GitHub github.com
- reStructured Text docutils.sourceforge.net/rst.html
- Docs Like Code: justwriteclick.com/2016/09/26/introducing-docs-like-code
- Tom Johnson’s 5+ hour API doc class (from 12/2018): idratherbewriting.com/learnapidoc/docapis_course_slides.html
- Peter Gruenbaum’s class on Udemy: udemy.com/courses/search/?q=peter%20gruenbaum&src=sac&kw=gruen
- Learn API Documentation 1: JSON and XML for Technical Writers: sdkbridge.cmail20.com/t/r-l-vdtjyud-jthdlteul-y
- Learn API Documentation 2: REST for Technical Writers: sdkbridge.cmail20.com/t/r-l-vdtjyud-jthdlteul-j
- Learn API Documentation 3: The Art of API Documentation: sdkbridge.cmail20.com/t/r-l-vdtjyud-jthdlteul-t
- Coding for Writers, part 1: udemy.com/coding-for-writers-1-basic-programming
- Swagger: udemy.com/learn-swagger-and-the-open-api-specification
- Attend TC Camp tccamp.org/2015/09/tc-camp-23-january-2016
- Attend TC Dojo sessions single-sourcing.com/products/tcdojo
- Find courses on the STC website: stc-sd.org/index.php/professional-development/education
- Watch for Write the Docs meetings writethedocs.org/meetups
- More resources from Andrew’s Webinar: stc-sd.org/index.php/professional-development/api-documentation
API doc skills are in demand — Opportunities
- Contribute to an open source project: apache.org
- GitHub open-source: github.com/open-source
- Open-source Friday: opensourcefriday.com
- Mission Pinball: github.com/missionpinball/mpf
- San Francisco Bay area direct content related opportunities: j.mp/sfba-tc
Your portfolio
- Put your portfolio online and link to it from your LinkedIn profile and your resume
- Focus on “open-source” style API references and tutorials, not tabular or encyclopedic content
- Include your contribution to an open source project
- See the portfolio section of Andrew’s site (synergistech.com)
Contact Andrew Davis
