Technical documentation

What is good content for developers?

How do we know if the content for the developer site and experience is good? As a foundation, content for these customers must be clear, concise, accurate, and structured. We use these attributes as we create new content and assess and improve existing content.

Clear

Sometimes we have to describe some complex stuff. Let’s make it as simple and direct as possible.

When defining a term, be precise. Use technical terms only when we know they’re common and easily recognized. And always simplify.

When describing steps to do something, number each one and make sure each step includes only one action. That helps us keep the steps simple.

Tip: One of the dictionary definitions of clear is “easily heard.” If you can easily read your content aloud, then it should be clear.



  • Don’t use OAuth 1.0. Use OAuth 2.0 instead.
  • Implement Intuit single sign-on with OAuth 2.0. It conforms to the OpenID Connect specification and is OpenID certified.
  • OAuth 1.0 is deprecated and should no longer be used.
  • This document explains how to implement Intuit single sign-on using Intuit’s OAuth 2.0 authentication implementation, which conforms to the OpenID Connect specification and is OpenID certified.

Concise

Keep content concise. Get rid of unnecessary words. Focus on only what matters to the developer at that time. They came to the site to get things done and concise, simple content helps them do it.

Concise content might not always be brief. Sometimes we have to describe complicated terms or steps. When that happens, take care to simplify the content as much as possible.

Tip: Feel free to eliminate extra words. Adjectives and adverbs are frequently good candidates to delete.



  • First, create the authorization request with parameters that identify your application.
  • To use the playground, you need to have a QuickBooks Online app. Don’t have one? Create it now.
  • Your first step is to create the authorization request with the parameters that identify your application.
  • The playground requires that you to have a QuickBooks Online app. Create a QuickBooks Online App if you haven’t already done so before proceeding.

Accurate

It’s hard to get things right. The technology can be complicated, details might not be completely clear or finalized, and things change. Errors can break the trust we’re trying to nurture and the apps our developers are trying to build.

To get technical details right, rely on subject matter experts to understand how things work and simplify describing them as much as possible. Subject matter experts should also review content for accuracy.

When the technology or standards aren’t completely set, clearly state that. The platform is evolving; developers like to be brought along as partners in the evolution. And they can help it progress.

When things change, update standards and documentation, and let developers know what changed. 

Tip: Regular reviews of new and existing content are the key to accuracy. Both content creators and subject matter experts should participate in reviews.



  • The QuickBooks Online API uses the OAuth 2.0 protocol.
  • Explore our new documents, SDKs, and other resources for QuickBooks Online.
  • QuickBooks Online APIs uses the OAuth 2.0 protocol.
  • Explore our new documents, sdks and other resources for QuickBooks Online.

Structured

Good content is structured. It has a job to do, and sometimes two or three jobs at once. For example, the headline on a page helps a user know what the page is about. It can also help the user navigate to the page and understand where the page and its content fit within the larger context of the experience. That’s a lot. We have to structure a headline to make sure it accomplishes all those things.

Structure helps us make sure our content is findable, understandable, and effective.

Tip: Sentences should usually be active, with simple verbs: Noun, verb, direct object. Keep lists parallel. Draft sentences so that links fall at the end.



  • Sign in to My Apps and select the app you’re working on.
  • Select the Keys tab to get development or production keys. If you’ve been using OAuth 1.0, you’ll see two tabs: OAuth 1.0 keys and OAuth 2.0 keys.
  • The OAuth 2.0 playground is a tool to walk through each step of both the OAuth 2.0 and OpenID Connect workflows.
  • To begin, get your OAuth keys from your app’s Keys tab of your Intuit Developer account.
Link copied