Monthly Archives: June 2015

How Interactive Documentation Can Be an Effective Teaching Tool, Part 3

Documentation, InfoQ, Metadata-Driven Design

So, let’s take this example of a project being constructed with metadata-driven design, and we’ll choose the ubiquitous Confluence as our wiki’s platform for hosting this project’s documentation. After we’re finished with the necessary prerequisite steps for creating our wiki (creating a Space, making templates, etc.), we write a page for our online manual, specifically about the dynamic nature of our system’s data structures. Now, in order to paint a more complete picture for this explanation, we are ready to add an interactive segment. So, what do we do?

MDD.Auditing

First, we need to think of a succinct example with the main purpose of being an illustration. (In other words, its fidelity to the overall subject is less important than its ability to convey the point at hand.) In our case, we will choose to demonstrate the dynamic aspect of our data structures by using an example that will generate XML from a user’s input. In order to accomplish our stated goal, the list of available tools can vary depending on the chosen platform. As one option, Confluence allows the use of Javascript within their pages, and the inclusion of JQuery is provided by default. You will have to execute the administrative option that allows custom HTML within your Confluence pages, and by doing so, you could leave your wiki vulnerable to attack. If this form of insecurity is not acceptable, another option is available: Confluence plugins. There are a number of Confluence plugins available to be purchased that can provide our sought functionality (such as Balsamiq, Protoshare, and Bob Swift). If you’re feeling particularly adventurous and have a penchant for danger, you could utilize the Confluence API and integrate external servers with your wiki system. In our case, though, we want to have the power inherent in a programming language, so we will accept the small risk associated with allowing the use of actual web programming. Instead of simply having an image of a table (as shown in the screenshot above), we will generate an editable table within our wiki page through the use of HTML and Javascript. On the right side of our wiki page, we will place a div tag, of which we will dynamically update with the contents from our modifiable table:

MDD.Auditing

Even though it might require some investment, such a small utility can convey so much of an idea without the usual amount of required verbosity.

How Interactive Documentation Can Be an Effective Teaching Tool, Part 2

Documentation, Metadata-Driven Design

So, how should we go about creating and presenting our interactive exhibitions to our documentation’s readers? In order to learn from our predecessors, we should look for inspiration from similar tools that are already available to developers. For example, JSFiddle provides an easy-to-use platform for both creating and sharing code samples of Web development. Many online tutorials link to JSFiddle sessions in order to evince specific points, and the readers can modify and execute these working examples in order to fully grasp the material. So, if it’s good enough to further the coding skills of developers, why can’t a similar paradigm help to further a developer’s understanding of an overall design? Today, many software companies and IT departments make use of a wiki in order to explain their various proprietary software and systems, and there’s no reason that we cannot leverage one of these platforms in order to create a JSFiddle equivalent for our potential audience.

In the spirit of demonstrations that showcase working examples, let’s create one of our own in order to prove the viability of this practice. In a previous article at InfoQ, I discussed the potential of using metadata-driven design in order to build a flexible scheme for your infrastructure. So, what exactly is metadata-driven design? For the sake of brevity, it can be summarized as an approach to software design and implementation where metadata can constitute and integrate both phases of development. (In other words, it’s a way in which developers can employ Agile iteration over the entire software lifecycle.) Of course, the ideas behind using such a design method can be abstract, and some of its finer points can seem less than tangible to the mind at times. However, if we were to offer some way of interacting with these ideas, they could become more empirical to the reader.