Ted Spence, Director of Avalara's API Team, shares tips and tricks for creating and maintaining quality and actionable API documentation.

1. Tips and Techniques
2018-10-10 - Ted Spence - Director, AvaTax
API

2. • Learned programming in Microsoft Basic
on a Commodore PET
• BA Philosophy, Cal State Fullerton
• Built Avalara’s sales tax return filing
system
• Started building AvaTax REST API in
2016

3. Documentation is how we
program people

4. People aren’t machines
We all skim the material
Different learning styles

5. To write good docs,
everyone must care
Let’s see how we can do it

6. Write down everything you’re told
Leave documentation for the next person who
gets hired
Wikis are a great way to get started

7. Answer every support question with docs
If you don’t have docs for that question,
write!
Great way to find topics for blog posts
… okay, maybe write docs after you get the
same question three times

8. Your requirements are your docs
If they’re too complex they help
nobody
This is why agile “Stories” are
helpful

9. It’s okay to just edit for someone else
Link docs together (wikis are great)
Give constructive feedback
Did they forget to mention something?
Can you rephrase it?

11. Don’t remove something
you saw twice
People find docs in
different ways

12. Original copy for AvaTax “SalesOrder”
objects:
Sales Order, estimate or quote (default)
This is a temporary document type and is not
saved in tax history.

13. Sales Order,
estimate or quote
(default)
“Represents an
estimate, or a sales
order, or a quote.”
Lead with the most common word!
Use full sentences!

14. Add purpose:
“This document type is used before a sale
has occurred to estimate the final amount of
tax to be paid when the sale is completed.”
Compare to Sales Invoice:
“This document type is used to record a
final transaction and calculate the final
tax amount with all necessary information.”

15. Keep track of what people get confused about
“For a sales order, the `companyCode` of the
transaction refers to the seller and the
`customerVendorCode` refers to the buyer.”

17. Use links to your
advantage
Remind people of good
stuff
Examples help a lot!

18. “How should I use this?”
I need to know why
Is this right for me?
Teach me best practices?
You need a User Guide
“I can’t remember …”
I know kinda what I want
Not sure about some
detail
Maybe need an example
You need Reference Docs

19. • Focus on facts
• Bullet points
• Methods and
Models
• Explanations of
fields and
parameters

20. • Tell the story of
how the APIs fit
together
• When do you use
each one, and why
• Link to reference
rather than too
much detail

21. If you write good docs,
you’ll feel like you’re
repeating yourself
It’s okay!
Some customers struggle
with the basics
Others need details

22. Ted Spence
https://tedspence.com
Twitter: ted_spence
LinkedIn: Ted Spence
ted@spence.net