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

Let’s be clear: Sometimes we have to describe some complex stuff. Let’s get 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. We can check the word list to figure out how to use specific words and phrases. 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.

Do
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.
 
 
Don’t
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. 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.

Do
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.
 
Don’t
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 isn’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, let developers know. 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.

Do
The QuickBooks Online API uses the OAuth 2.0 protocol.
Explore our new documents, SDKs, and other resources for QuickBooks Online.
Don’t
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, and it can also help the user find the page in the first place 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.

How do we write structured content? Follow content standards and guidelines. We document many of them in the QuickBooks Design System. We’re also developing new templates for documentation, and those will present standards for headlines, subheads, definitions, numbered lists (steps), and other content elements.

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.

Do
To walk through both OAuth 2.0 and OpenID Connect workflows, use the OAuth 2.0 playground.
  1. Sign in to My Apps and select the app you’re working on.
  2. 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.
Don’t
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.
 
 
 
 
 

 

  • Was this Helpful?
  •