User Experience at IU

Clear, concise, and comprehensive documentation is your best tool for encouraging developers to use your service, fostering goodwill towards your team, and reducing unnecessary support requests. The strategies described on this page are intended to help you make the most of your service’s documentation.

Be brief

Developers have limited time to read documentation and research new technologies. Be mindful of your reader’s time by keeping your documentation as concise as possible.

Put documentation about your service’s most common use cases or most frequently-encountered issues front-and-center so that your reader can find this information quickly.

Write for all skill levels

Write so that developers of all skill levels can understand your documentation. Many IU developers are beginners, and even experienced developers may be unfamiliar with your particular service.

If your documentation covers a topic specifically for expert users, warn the reader at the start of your page. Redirect beginners to a more appropriate resource if one exists.

Use plain language

Writing your documentation in plain language helps make your instructions easier to find, scan, understand, and act on. Jargon or complex language can confuse your reader and potentially reduce their trust in your service.

If you have to use a technical term, help orient the reader by calling out the term’s definition the first time you use it.

• What to avoid: “All GET requests made to the API are idempotent.”
• What to aim for: “All GET requests made to the API are idempotent. An idempotent HTTP request has the same effect on your data no matter how many times the request is made.”

Focus on a single task

Each page of documentation should walk your reader through one specific task your service allows them to complete. Avoid presenting more than one topic to the reader at the same time, as doing so is likely to confuse or distract them.

Show one way to complete a task

Showing your reader more than one way to complete the same task can be confusing, especially if the reader is trying to use your service for the first time. Show only the easiest, quickest, or most common way for users of your service to complete the task.

If there are situations or use cases that call for a different approach to a particular task, defer that information to another page of your documentation. Make it clear when and why your reader would choose these alternative approaches.

Avoid ambiguous statements and generalizations

Be explicit in your instructions and explanations. Provide your reader with everything they need to know to complete their task with your service without having to experiment or inspect the service source code.

• What to avoid: “Depending on the method you use, you may need to provide your API key and secret.”
• What to aim for: “Methods Foo and Bar require your API key and secret.”

Avoid qualifying statements

Qualifying statements—author asides, warnings about pitfalls, and discussions of edge cases—slow down comprehension and distract the reader. In most cases, a qualifying statement is too much information too soon.

If you must call attention to an aside, pitfall, or edge case, defer their explanation until the end of the page or highlight them in callout boxes apart from the main text.

• What to avoid: “Unlike videos, audio clips, and other media, which have different methods for providing text alternatives, images use the alt attribute.”
• What to aim for: “Use the alt attribute to provide alternative text content for images.”

Provide complete examples for each use case

Your reader shouldn’t have to experiment or inspect your service’s source code to learn how to use your service.

If your service allows developers to do more than one thing, such as reading, writing, and editing data, give complete examples for each task.

Link out to documentation for other services

Avoid reproducing documentation for other services—leave that to the maintainers of those services.

By reproducing documentation, you risk confusing or misleading your reader if that other service changes but your documentation doesn’t.