Category Archives: Documentation

So, I attended a Redis workshop a few days ago, at the New York “campus” (which is a buzzy, DB-esque industry word that I loathe) of Galvanize. Even though I usually don’t go for these meetup/workspace type of places, I’ll admit that this one was rather pleasant. Unlike other places, it did a good job of finding that fine line between casual and professional. For example, no beanbags anywhere. Because as much as I love beanbags myself (i.e., I have two at home), we can’t look at your screen together unless I get on my knees or I crawl onto the beanbag with you…which might be uncomfortable in many ways for the both of us. Plus, the space had reliable WiFi for most of the time I was there, unlike some other places.

Even though I’ve already been dealing with Redis at work for a little while now and generally impressed with its performance, it never hurts to try and learn something from the masters. (Unfortunately, AntiRez himself did not leave Sicily and fly over to teach us.) I was curious how they were going to showcase the tech and if we were going to just sit there and watch, when they instructed us to download Docker. As it turned out, we were going to learn the lesson via containers with Jupyter Notebooks, which I had never heard of before. And since I yearn for the era of interactive documentation, I couldn’t have been happier. (On a side note, I only recently learned about KataCoda, which I love just as much, if not more.)

Even though the second half of the day was your familiar salespitch for Redis Enterprise and Redis Cloud (which did seem to be an appealing purchase), the first half of the day was when they taught about the product itself. For the most part, it wasn’t anything new to me, aside from the occasional bit of trivia. (Lua is the language used by the Redis CLI? Huh. It’s come a long way since being just the scripting language for WoW skins.) I did learn a few tidbits about the data structures (like the existence of HyperLogLog), but since I use Spring Caching in our microservices, we don’t pay that much attention to them.

Instead, it was interesting to learn about the features of Redis that we weren’t even leveraging yet at work. For example, you can write your own extensions to Redis using C. Which I’d be tempted to do just because, since I miss writing in C…Also, it was interesting to learn about the various modules that were already available for Redis, with functionality ranging from machine learning to bloom filters. And that’s when I recognized a pattern seen before. Much like every other tech company, there seems to be the desire to get into whatever is hot, to survive as a company by being more horizontal. However, I would implore Redis to be careful and to never neglect your core mission. I, for one, don’t really need machine learning, but I’d like Redis to work with Spring (i.e., Pivotal) to further develop the Spring Data Redis layer and make it configurable, so I can easily direct reads to slave nodes. I need that, not machine learning. So, even though I didn’t learn a great deal about Redis by attending, I got to see the general direction of the company. In that way, I’d say that the trip to Galvanize was worth it.

That, and spears of fresh fruit.

You just can’t argue with fresh fruit spears, where the fruit is cut into various geometrical shapes. It just plucks the right strings of geeky hearts.

As I take more responsibility over the web services within our department, I’m trying to be more standard in its development and maintenance, including its documentation. While learning how to correctly implement Swagger pages for our services (and, yes, I know, I’m late to the party), I stumbled upon this particular wonderful little feature: interactive documentation!

A couple of years ago, I wrote a piece how documentation should be more interactive, since that would ultimately result in a more effective tool to teach people about anything (an API, a programming method, etc.). Now, since it was actually introduced years before I wrote that piece, you can say that I’m actually behind my time. I’ll accept either. Even though it’s a more basic version of the idea presented in my post, it’s still cool that there’s some work being done in that direction. Much-belated kudos to the Swagger team!

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?

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:

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.

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.

For the most part, college professors are an odd breed. As a student, I received some amount of education from them, but I was always more entertained by their eclectic personalities and by their proclivity to become volatile at the drop of a hat. Even though some of them had the ability to entertain me with their odd quirks, my favorite professors of computer science were the few who had both mastered the subject and possessed a keen passion for conveying its principles to a room of nascent minds. In my opinion, their greatest tool was the working example. Unlike their more pedantic colleagues, those mentioned few would spend less time simply being loquacious. Instead, they would engage their students through presenting problems on the blackboard and collaboratively helping the students to solve those problems. Even their assigned homework would contain working examples that were obviously treated with meticulous care; unlike other professors’ assignments, they nearly always compiled without an issue and ran exactly in accordance with their given description. By having some concrete form of the abstract ideas presented in class, those code samples had the necessary weight needed to sink into the nether of my mind. With them, I had an established baseline, and by making code changes and then observing their consequential behavior, I could learn through experimentation. After discussions with my classmates, I found that I wasn’t the only one who placed such value in them. In fact, we all could benefit from the use of working examples whenever we learn something new. This sentiment isn’t restricted to an academic setting and can even be applied to the workplace. For example, documentation of IT projects can be thoroughly descriptive and can convey some broad sense of an architecture, but even they can use the inclusion of detailed examples in order to better illustrate an idea. In fact, with modern tools, it’s now possible to provide user-friendly, interactive sessions that can showcase the various facets of an elaborate design. With them, a stakeholder can thoroughly absorb the presented blueprint for an architecture within an online manual, idiosyncrasies and all.