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.
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.
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:
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:
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.
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.
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:
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:
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.
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:
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!