How to improve examples for JavaScript library

SurveyJS released a new version of the examples for our library, and we would like to share our experience.

Here are the most important points:

• interactive live examples
• examples with instantly applied parameters and result
• the complete source code
• the capability to open any example in a playground (plnkr, jsfiddle, codepen etc)

SurveyJS examples

Interactive live examples

When a programmer writes code, the most important thing is to see the result of code execution. Looking at an example, a user wants to see it in action but not shown in a picture. In SurveyJS, you can run a survey to handle the code and see the result.

Examples with instantly applied parameters

OK, now, our user is interested. Some questions that may arise:What about a property? What if you change it from true to false?

Yes, we know that customers have descriptions. However, do they want to delve into them? Probably, they are clearly described. So, the way out is easy. Examples in SurveyJS allow users to fine-tune properties. They can change the basic settings and instantly see the result.

The complete source code

Previously, we provided a part of the source code which worked with an applied functionality, but it did not contain the full environment — external libraries, styles, and other resources. As a result, we had issues related to specific environments. We had detailed descriptions of circumstances under which the problem occurred, but we were unable to reproduce them due to different environments.

At this point, we came up with the following:

• provide complete source code
• provide the capability to run each sample in a playground — we use plunker

Now a user can copy and paste the code from corresponding tabs (JS, CSS, HTML) with the whole environment, dependencies, and styles. All the necessary information is included!

Thanks to this new approach, a user feels more comfortable with the provided code and can take our example as a ready boilerplate.

Open examples in a playgound

Now a site visitor becomes your product user. They can play with live examples, try different settings and… find a bug! Yes, a bug in your brilliant and covered 100% with a test library! Now your user wants to create a bug report. They should explain the current behavior in as much detail as possible, the steps necessary to reproduce and illustrate the code.

All this becomes simpler with the “Open in Plunker” button. A user can now open any example in the playground, change it, and provide developers with a link your plunk’s fork. This makes resolving issues easier, helps you share your findings with others or helps someone on StackOverflow.

Plunker as a playground

As we did not find a detailed explanation on how to open your example in Plunker, we decided to tell you about this platform .

Why Plunker?

We chose this platform because each Plunker sample is a complete project with a set of files and folders, which you can download as a ready-to-use website.

For example:

To send a request to the Plunker API, we are creating a hidden form with input fields and information about tags, plunk privacy, and example descriptions. We also add input elements for plunk files’ content (JS, CSS, HTML). This is how we start an anonymous plunk, which can be saved and reused in the future.

UPD (8/24/2017) : We’ve added “open in editor” button for open example in our visual editor. For example: https://localhost:44388/Examples/Library/questiontype-radiogroup/jQuery

You can find full code in this file in our github repository.

Thank you for your interest, SurveyJS team