Time to read: 5 minutes.
© 2001 Mike Slinn.
See the background material in Cost-Benefit Analysis for Documentation.
I spoke with a technical support manager at an enterprise software vendor who must remain nameless. This well-known vendor has a technically complex product that has a reputation for being difficult to install and to use effectively. The technical support manager attributed the cause of the problem to their poor documentation. He computed the cost to his company for their own poor API documentation at half a million dollars per year, and estimated the cost to the system integrators who use their products at $127,000 per year. Although it was harder to estimate the cost of lost sales due to poor documentation, he felt those figures would be much higher.
A documentation manager at another well-known Fortune 500 software company said to me in confidence that “we just assume that documentation is important, and try to do the best we can with the resources that are made available to us. We have never considered measuring the impact of the quality of work that we do on the success of the product, or the product’s profitability.” To be sure, few senior executives are likely to allocate resource to a project because it is the right thing to do – they want tangible justification, usually in terms of increased revenue, decreased cost, improved market share, etc. in order to grant approval.” Possibly this disconnect between technical management and senior management explains why so much documentation is of low quality. Senior management has yet to see a proper business case that demonstrates an impact to their bottom line.
Overview
Programmers have a reputation for disliking writing documentation, yet as we have just seen, their managers are also to blame for poor documentation quality. Regardless of who is to blame, end users of software products that have APIs find that the value of a given software product depends a great deal on the quality of the documentation provided. If they can’t understand how to program to an interface, they can’t use the product.
Just as a picture is worth a thousand words, working code examples are extremely valuable to someone who wants to know how to use an API. While writing documentation for the Apache Tomcat project, I felt that the existing servlet specification from Sun was somewhat inaccessible to the average programmer; only by devoting a considerable amount of time could a newbie learn how to program servlets and JSPs. The oft-repeated complaint of computer manuals echoed in my mind: “one needs to know how the system works in order to understand the documentation”.
Tomcat, like many enterprise systems, has setup requirements that often confuse newbies. Again, the ‘catch-22’ of needing to know the system in order to be able to set it up in order to learn about it made me feel that something more than listing of small programs was required – some way to ‘bring them alive’ was needed.
Programs need a context in order to run an operating system, a runtime environment, and apply a configuration, and often need a runtime data feed or co-operation with other programs. I decided that what was needed was a way to provide a ready-made context for newbies. Wouldn?t it be nice if a web page had a ‘try it’ button next to a program fragment that would bring the fragment to life? What if the reader could click on the ‘try it’ button, thereby running the fragment, and producing output? Thus JSP Explorer was born – a documentation aid for readers to learn by example.
Learning by doing is a very good way to learn something new. By experimenting with and altering program fragments, newbies can quickly understand an API or learn a new language. With a tool such as JSP Explorer, the person who must document an API can discuss working program fragments, instead of attempting to write a narrative. This more focused type of writing is often much easier for technical people.
About JSP Explorer
JSP Explorer allows a reader to click on Javadocs or an HTML page and run the code in a browser window.
The code can be modified and re-run.
The user can also type in ad hoc program fragments and execute them.
Program fragments can be written as JSPs or as Java code in an HTML frame, and the output is delivered to another HTML frame.
At any time, the current program fragment can be ?captured? as an HTML table containing an HTML button with the attendant program fragment displayed next to it.
This HTML code can be pasted into an HTML document, or into a Java program for later processing by Javadocs.
Readers of the documentation can invoke the sample code merely by clicking on the HTML button.
Here is an example – click on the ‘Try It!’ button.
int num = 11; // Change this number to set the times table for (int i=1; i<=num; i++) out.println(i + " x " + num + " = " + i * num); |
JSP Explorer complements your favorite IDE, and is not meant to replace it. A plugin for JBuilder is available that lets you create JSP Explorer ‘Try It!’ HTML from by highlighting sample code from within JBuilder editor. You can paste the code into the Javadocs or into another document by using your favorite HTML editor.
How JSP Explorer Works
JSP Explorer is a server-side application that builds program fragments into complete programs, compiles and executes them. It can work with applets, JSPs and server-side Java programs.
JSP Explorer has two frames (shown above). The top frame is where the program input(s) and parameters are specified; controls also live here. The bottom frame (displaying the 'About JSP Explorer' heading) is where the output is displayed and applets run. The blue line separating the two frames is movable up and down. If you click on the blue Help complete documentation and examples are displayed in another window.
Summary
JSP Explorer doesn’t address every reason for poor software documentation, but it does provide for a quick and easy means of generating example code so that readers can learn from example – and this type of documentation is the type that programmers find easiest to generate.
Software quality provides tangible cost benefits to all parties, yet because metrics are not utilized, most vendors, system integrators and end user companies are unaware of the costs that they bear for inadequate documentation. The ability to bring a code fragment to life can dramatically reduce the learning curve for a programmer tasked with learning a new API. The use of JSP Explorer eases the burden on programmers to document their code, and increases the productivity of all stakeholders in a particular software API.
