I am very excited because today we released the first version of a project I’ve been working on for a few months. It’s called LearnWijmo, and it’s a tool that I hope will make it easier for people to learn how to use our JavaScript UI library. 
If you are curious or impatient, and don’t care to read about LearnWijmo’s background, motivation, and design process, feel free to click this link and jump in right now. You can always come back later. I have been using and developing software for quite a few years, and documentation has always been a major topic for me. So let me recap very quickly why we decided to create LearnWijmo and why it is built the way it is.
The old days: CHM files
In the old days, things were simple. You wrote a long Word document, ran it through a tool to create a help file, and shipped the help file with the product. The tool took care of building an outline, an index, and all inter-topic links. This worked well as long as you had a good team of technical writers and didn’t release too many products too often. Maintaining the source documentation up-to-date and in sync with the product was a big challenge.
Automated Documentation: The Good and the Bad
Things started to improve when Sun created JavaDoc, a set of tools and standards designed to make software documentation easier (circa 1996). The idea was to embed the documentation in comments right in the code, and to use a tool to extract and format those comments into help systems. The idea is comments are much easier to maintain, and better integrated with the code. The idea worked, and other companies soon followed the example. Microsoft for example introduced XML documentation comments in C# from its first release. Embedding the documentation in the source code is a great idea because it makes it simpler to keep the documentation in sync with the product. But it poses a new set of challenges:
- It encourages the creation of “automatic” comments, a knee-jerk reaction that tempts developers to write comments such as “isAsync: gets or sets a value that determines whether the process should be performed asynchronously”. Doh…
- It shifts the documentation task from technical writers to developers, who have a completely different skill set. Asking tech writers to review the documentation and submit changes to developers periodically is a possible solution to this problem; another is to give tech writers access to your source control system so they can edit the comments themselves. Either way, it’s not as simple as simply writing some comments and hoping that will lead to stellar-quality documentation.
- Even when done perfectly, source code comments only address the reference documentation, which defines each part of the product's API. It does not help much with the narrative documentation, which explains how to use the product and can include step-by-step instructions.
Supporting Materials
There’s no question automated documentation is here to stay. It has its challenges and limitations, but it does solve the problem it was designed to solve, which is generating and maintaining reference documentation that is complete, accurate, and up-to-date. The next challenge is how to create additional content to support the reference documentation. I believe this requires a combination of elements:
- Frequent blogs, focused articles that explain new concepts and contain information that can be used to solve specific problems.
- A good set of sample applications, designed to demonstrate typical usage scenarios and how to combine multiple products and features to achieve a certain result.
We have been working very hard to generate (and link to) quality blogs and samples that help users understand our products and the concepts behind them. We will continue to do so because both the existing API documentation and narrative content like blog posts are important to a complete understanding of Wijmo.
The Missing Piece
Even with a good set of reference documentation, blogs, and samples, we felt there was something missing. A piece that would bring all these things together and play the role of an old-style printed manual or a course, something you could browse through to get a general understanding of the product, or dive into to understand the details. Our first attempt was an “Explorer” application divided into sections to highlight each important feature of our products. This idea worked fairly well. You can run the Explorer and check it out for yourself. The main problem with the “Explorer” is that it showed what you could do with the controls, but not how. To see the source code, you had to download the application or search through a project tree. We ran into another problem as we added more controls, features, and framework support to Wijmo: the Explorer sample started to grow too much and became hard to maintain. We also created a series of “101” samples that focus on single modules, to show source code side-by-side with running examples. For example, we have InputIntro, FlexGridIntro, and FlexChartIntro samples that follow this pattern. These samples do a great job of showing the basic functionality of each control, along with the source code required. The problem with the 101 samples is that they are a little hard to maintain, and do not allow users to experiment easily. To try out an idea, you still have to download and modify the code.
Requirements
After talking to customers and to members of our own teams, we decided it was time to create something new. Something that would make it an order of magnitude easier for people to learn what Wijmo is and how to use it. We started with some requirements:
- Useful We wanted users to be able to see running examples along with the source code. We also wanted to allow users to experiment by making changes to the code and see the results instantly.
- Comprehensive We wanted a tool that would cover all Wijmo modules and controls, to whatever level of detail we (and our users) felt appropriate. More complex controls and features should be backed by more documentation and samples.
- Flexible We wanted to create something that could be expanded easily as we added more features to the product. Adding new topics or re-structuring existing ones should be easy. We wanted to be able to easily add topics or add depth to existing ones.
- Scalable We wanted to create a small, efficient application in the spirit of the web: Distributed, granular, easily accessible to users and content contributors.
- Maintainable We wanted the application to use the latest release of our products by default. Whenever we release a new version, the app would automatically upgrade to it. We work very hard to avoid breaking changes, and this provides even more encouragement. We also wanted to be able to add content to the application very easily, often in response to questions asked by users.
- Contextual We wanted the application to show related topics together, in the same hierarchy. It should be possible to re-use content, with different items in the content outline pointing to the same topic, but viewed as part of a different context.
Architecture and Implementation
After much thought and debate, we decided on a very simple and powerful design. The LearnWijmo application would have a hierarchical table of contents on the left. Each topic in the table of contents would have a corresponding fiddle that would be displayed when the topic is selected. That’s all. I told you it was simple! We did discuss which fiddle tool we would use. This was a big decision because we knew we would be creating a lot of these examples, and really didn’t want to switch tools any time soon. We settled on JSFiddle because:
- JSFiddle has been around for a while. It is mature and is consistently ranked as one of the top fiddle tools.
- We have been using fiddles in our on-line documentation since our first release, initially as links and later embedding them. The tool has always served us well, and has become better with time.
- JSFiddle has built-in support for TypeScript, React/JSX, and Angular 2 (2.0.0 for now). So if we decide to create fiddles to demonstrate our interop modules, that should be easy.
We also discussed which framework, if any, we would use in our fiddles. We decided not to use any, sticking to pure JavaScript whenever possible. This ensures the fiddles focus on the controls rather than on the framework. Most of the examples are so small they don’t really benefit much from frameworks.
First Release
We have been working on this concept for a few months. A lot of time was spent creating outlines that introduce each module and control in a logical and comprehensive way, and even more time creating some 300 fiddles packed with useful code examples. Here is a screenshot of the app in case you are not connected to the web and can’t open it now: 
The first public version of the LearnWijmo app covers the following Wijmo modules:
- Core (wijmo.js)
- Input (wijmo.input.js)
- Grid (wijmo.grid.js)
- Chart (wijmo.chart.js)
We have published the LearnWijmo app as a sample as well. Feel free to check the source code, it’s a good example of how to use and style our new TreeView control. The app also has an interesting routing method that does not require any frameworks or plug-ins, and supports topic-specific URLs. We will soon add more modules, including Gauges, Navigation, and Olap. We will also keep working on the current modules, hopefully guided by input from our customers. I hope you enjoy our new LearnWijmo tool, and that you help us improve it! Thanks!
MESCIUS inc.