Setting Expectations

👉 Writing Tip #2: Leverage spacing

Key points in this video

When creating documentation, it’s important to set expectations. These expectations come from empathy—being able to put yourself in the shoes of your consumers and colleagues.

Set expectations for what you want and what you don’t want.

What you don’t want (or things to watch out for):

  • Incorrectness: Docs don’t match actual API behaviour
  • Incompleteness: Documentation is missing key information
  • Bloat: Too much information at the wrong place
  • Inconsistency: Different terms or UIs are used to refer to the same concept
  • Complexity: Documentation is written with confusing or complex language.
  • Ambiguity: Documentation is unclear and forces readers to guess
  • Obscurity: Documentation is hard to find or navigate
  • Fragmentation: Documentation for one resource or task is scattered across multiple pages or locations

What you want (or things to aim for):

  • Correctness
  • Completeness
  • Conciseness
  • Consistency
  • Clarity
  • Accessibility


Don't obsess over perfection. Focus on doing the best you can, and being willing to improve.

Practice makes (close to) perfect. Start with manually looking out for these pitfalls and targets, and over time, they’ll become a part of you.

Exercise

Browse through the documentation sites listed below. Based on what you’ve learnt about expectations, identify some positive and negative expectations. You can share your thoughts in the course Discussion area.

Tip: It might help to pretend you want to use the API for something specific. Think through the process you’d use and the information you’d need. How would you go about it? Do the docs have the complete information you need? How easy is it to find it in the docs? Here are some sample use cases:

  • Yelp: You want to find businesses hosting free fashion events close by.
  • Reddit: You want to post the event and business information to a subreddit called “eventsandbusinesses” (or create it first if it doesn’t exist)




Complete and Continue  
Discussion

1 comments