Best Practices

When creating your application or integrating with data.world, it’s best to keep your users in mind. Always be thinking of what will benefit them and what might get in the way of people using your app to the fullest.

Language & Tone

Make sure that when explaining your product to end users you keep it simple, informative, and approachable.

  • Using “you” or “your” is preferable to referencing “the user” (Ex: “Access your data and create charts with a few simple clicks”, instead of “Users can access their data…”).
  • Explain the functionality of your product clearly and directly in any area where you’re interacting with your users
    • Keep it concise and clear without trying to serve them too much information at once (break it up into smaller chunks if trying to convey a lot of information).
    • Let your voice through, but avoid being overly friendly or “cutesy”. You’ll want users to feel like they’re interacting with a human, but the most important thing is to always communicate your point clearly and effectively. Too many jokes, puns, or colloquialisms can distract from your point.

Remember that your users will come from varying backgrounds, races, sexes, and experience levels. You’ll want to direct any instruction to a variety of users.

  • Use you/yours/they/their instead of he/his or she/hers and avoid assuming specific knowledge from your users.
  • Stay away from jargon and slang, and make any action items short and specific.

Use Cases

Have a clear idea for how users will get the most out of your application. It’s best to plan interactions step by step to make sure the process goes smoothly.

  • Will your application be independent of data.world, or will users interact with both your product and the data.world site?
  • Will your application allow users to import data?
    • What about exporting it back to data.world?
  • Will you support queries?
  • Do you want to authorize users with OAuth or Tokens?
  • Will you send notifications with webhooks?
  • What does a typical workflow look like?

These are all good questions to ask yourself before beginning your project. To know what you can accomplish with data.world, take a look at the API Reference or check out the Integrations Gallery to see some featured existing integrations.

Onboarding

Onboarding users effectively will make all the difference when it comes to adoption and return-usage of your integration. Here are some things to consider when onboarding new users:

  • Is the product or language you’re using well known, or will users need some introduction to get started?
  • Are there any prerequisites for users to start using your integration? (Installed applications or libraries, version requirements, etc.)
  • Is there a way users can contact you with issues?
  • What are the primary tasks a user should be able to accomplish when using your integration?

Answering these questions will help you develop an onboarding plan that will help your end-users adopt quickly and continue using your integration in the future. Always keep in mind language & voice and use case to help guide users correctly so they can get the most out of your integration.

Check out the Getting Started page for KNIME that helps users understand how to connect data.world and KNIME.

Failing Gracefully

There’s always a chance that something can go wrong when someone is using your integration - that’s why failing gracefully is so important.

Make sure you include error messages that will help the user understand what went wrong - did they open the wrong file type or use the wrong link or authentication token? Including the right information in your error messages will ensure that the user doesn’t make the same mistake again.


Error messages from the KNOTS integration allow you to see the issue (Critical error - access denied), and a quick option to re-configure your knot.