Dan Bricklin's Web Site: www.bricklin.com
Home Writings	AlphaRef Reader: Tablet-first design of an app for reading reference material The story of how it came about < Dealing with Disconnected Operation in a Mobile Business Application: Issues and Techniques for Supporting Offline Usage    Thoughts on the culture that gave birth to the personal computer >
	I just released a new app for iOS and Android: AlphaRef KJV. This is the story of how it came about. As a point of reference, here is the initial Overview Video for the app when it was first released: Video on YouTube Writing documentation As part of my work as CTO of Alpha Software Corporation, I have been working on the start of some new documentation aimed at technically experienced users. This was both helpful to me, since I was writing part of the documentation that I would want personally and got practice describing the technology, and to Alpha the company, since it was getting additional documentation written that it could provide to customers. As I completed the initial "Overview" chapter and sent it out to some people for comment, I realized that I was missing something. I had written it in a simple text format and people were reading it using traditional means -- mostly just scrolling through a simple, mechanical HTML conversion in a browser with appropriate formatting. I realized that when the complete "Programmers Guide to the Alpha Anywhere UX Component" was done (or even parts of it), I, and other developers, would expect to read it on a tablet. After all, this is documentation for developers creating mobile apps. I needed to be able to deliver it in a manner tailored to the tablets the developers would have sitting on their desks. Using a paper version, like I do with JavaScript with the O'Reilly "The Definitive Guide", or a CSS "pocket reference",  would be embarrassing -- like the proverbial shoemaker's children not having shoes. I didn't want to require a second monitor and go mouse-centric. I wanted, though, something that felt as good as or better than a paper book with lots of Post-It bookmarks. Trying to find an app tuned to reference material I looked around for examples of reference documentation like this provided in a format tuned to tablets and efficient reading. I found very little. There are lots of PDF readers, but those are very much page-oriented, built around paper pages that need to be zoomed in and out. I had used the O'Reilly JavaScript book on a Kindle, but found it much too cumbersome compared to the paper book (though it is a lot lighter in weight). I found some simple readers for particular documents, but they were very much custom-built for the particular document. There are lots of news readers and book readers, but those were for something that you either read from cover to cover or jump around in for serendipitous discovery, with hopes that you'll spend a lot of time with it. There are special formats for such documentation, like DITA, but the common output for that is even harder to read on a normal computer, let alone a tablet, being broken up into the most Web 1.0 of reading experiences. The focus seems to have been on authoring and not reading. That seems out of balance to me, especially for reference material that is used for "just-in-time" information on mobile devices as part of a job that needs to be as efficient as possible. I wanted something tuned to reference material. That is, I want to be able to find information that I need (or find that it's not there) quickly, and be able to re-find something that I referred to in the past easily (a common need -- we don't all have photographic memories of detailed specifications or instructions, but we do remember that we saw it). I also want to be able to skim through the material to get general ideas and for serendipitous discovery so I can know that I can find things in the future that I need. I want to minimize the time that I use the reader when in the midst of doing a task. Specifying the app that I want I've been building tablet and phone apps for many years (both in the old "pen computing" days of the 1990's and natively on iOS from before the Apple iPad come out), and I had some ideas for much of the functionality that I'd want: Scrolling with a finger for reading and skimming, scrolling through titles and short summaries of major sections, searching, and a pasteboard of some sort for bookmark navigation. Some of the concepts I mentioned were articulated in my work on the original Trellix product almost 20 years ago that was aided by various consultants in the journalism and neuropsychology fields, as well on the www.GoodDocuments.com web site that I authored in 1998 based on consulting from journalism professor Chris Daly. That is: Having bookmarks, with appropriate cues like color and short text, organized on a two-dimensional space by the user, is a useful way to navigate among dozens or even hundreds of pages, and headings and sub-headings (written appropriately as "leads" of a traditional newspaper story as opposed to a "suck-them-in teaser that gives no information") aid in skimming, which is an important form of reading. I decided that the documentation would be structured in the normal "chapter", "section", "sub-section", etc., format (allowing a traditional printer/PDF version to be made from the same input), and that bookmarks could only be set to one of these sections or sub-sections ("topics"), with unique identifiers for each such part kept constant as new versions of a particular piece of documentation were produced. This would let those bookmarks survive updating of the main text. I also decided that I'd have the documentation for the reader start out as JSON-formatted data. JSON is less verbose than XML, the other common interchange format, is efficient to work with in a variety of computer languages, including JavaScript, and is easy to convert into from other formats, such as XML or structured databases. Finally, I decided that we'd start with just designing for the Apple iPad. I reasoned that other tablets would be similar enough in size to be handled, too. Since I planned to implement it using run-everywhere HTML5 technologies, I knew that concentrating on the popular iPad wouldn't box me in too much. Also, I wanted to do as good a job as possible on this popular and appropriate-to-the-task platform. Designing a reader app and choosing Alpha Anywhere and HTML5 for developing it I challenged the UX designer that I have been working with the last few years, Adina Bricklin, to come up with a design with the functionality I wanted that was appropriate for an Apple iPad. Adina (who is my daughter and has an MFA degree) has mocked up many iPad and iPhone productivity apps, some of which have been implemented, shipped, and used by many thousands of users, as well as a variety of web sites. A late-twenty-something, her designs are modern and lean towards what's best for the user and not towards what's easiest to program (that is, she's different than an old developer like me). The challenge was to convert her Adobe Illustrator (and later HTML and CSS) mockups into a fast, working application. I used Alpha Software's "Alpha Anywhere" development system to build the application. (Another "shoemaker's children" situation: As CTO of Alpha, how could I use some other development system?) This was a good test for Alpha Anywhere of taking a designer's work and turning it into an app, rather than starting with a working app and asking the designer to "make it pretty and user-friendly." This is always a question with a "coding optional", HTML5-generating system like Alpha Anywhere: Can you use the system to implement a design that it wasn't specifically created to handle? Is it customizable enough? Does the result feel enough like a "real" app? Implementing the app After seeing the initial screen mockups, and knowing the functionality that I wanted, I started implementing the major functional items. The first items were the various scrolling Table of Contents (TOC) lists with titles, summaries, and sub-lists. That then needed to result in the rendering and positioning of the main reading area when a particular section was selected by the reader. Also, the reverse needed to be implemented, so that a tap on the section heading in the text could synchronize the TOC lists. Alpha Anywhere handles scrolling lists quite well, and gives the developer a lot of freedom to use CSS for typography and layout. This meant that I could ask Adina for an exact spec of her design in HTML and CSS and use it with little or no modification. Next, I needed to implement my pasteboard for laying out bookmarks in a two-dimensional space. I used my experience as a JavaScript coder to build that from scratch, but I tried to implement it in a way that I could submit it to Alpha to perhaps make a standard component out of it, or out of something like it. I used the special touch event handling features of Alpha Anywhere to take care of tracking touch and drag events. The overall user interface for this was implemented using animated sliding panels that Alpha Anywhere provides. I organized them in whatever way was easiest to implement as I went along. Much of the Alpha Anywhere building environment uses dialog boxes and a tree view of the controls (lists, buttons, text areas, etc.) that I was organizing. In addition, I was adding to the CSS definitions, and a set of custom JavaScript functions, like "setCurrentTopic" to make sure that a particular sub-section was displayed in the main text area. As my implementation progressed and we starting seeing how it felt, it became clear that my organization of panels and overlays was not implementing Adina's UX vision close enough. It was close enough for me as a programmer user, but it wasn't tuned to the nuances of how to get from here to there that she envisioned. Luckily, I was able to refactor the high-level panel and overlay organization multiple times with little or no coding until we got something that felt the right way. We also continued to tweak things as we used it and tried different forms of content. Making search simple and fast Next, I implemented the search functionality. I wanted "as you type it" immediate search. Luckily, JavaScript is fast enough to do this, even on a relatively large amount of text. (It's often amazing how fast modern JavaScript can be for certain tasks.) To make it even better, I put the searching in timer-driven events that were interrupted and reset when the user added a new character to the search string. The results of the search are shown as a filtered, flattened list of all the topics that match. Tapping a row positions the main text display on the first match in the topic, with all matches highlighted in a color and the specific one double underlined (the wonders of CSS, HTML, and DOM manipulation helped here). There are "next" and "previous" buttons to move through all matches, taking advantage of the JavaScript object structure I used to store the topic information. A design challenge with search was the large number of matches that you might find. For example, for the word "check" in an HR document when you are interested only in payroll. Rather than design some complex filtering mechanism or hard-to-discover use of the state of the TOC list, we came up with a simple message on the "n of m matches" heading: "Tap for Table of Contents View". This toggled between all topics (which through their titles and summaries helped you know if this was a potential place to find the desired match) and just the top levels of the TOC (so you could just look in the main, top-level "Payroll" section and do "Next/Next/Next" from there). Not just for Alpha's documentation When discussing this app with some of the Alpha Anywhere users at various corporations, and showing them some early prototypes, it became clear that this app could fill a general need. Because it was written in Alpha Anywhere and customizable, it could be very valuable to departments we hadn't been talking to. They needed a means for distributing documentation of various sorts, from human resource material to repair documentation, and had nothing tuned to tablets. They also had special needs for instrumenting the reading environment for various reasons and having something with source code under their control would let them implement what they needed. So, this reading technology was another way for Alpha to get our system into the enterprise. This, of course, brought up the question about whether it could handle corporate-size documentation and how they could really get their hands on a working copy to evaluate. The decision to go with the King James Version The answer to those questions of capacity and availability turned out to be two-fold. First, I could create a sample app using the reader code that we could put in the various app stores for people to try. This would let them test out whether it really did look and feel like a "real" app (and really is "write once, run multiple places"). Second, if I found a large enough existing document that they were familiar with that was appropriate for this treatment, they could try it on something "real" and not feel that we cheated with the design of the sample text. After thinking about it for a while, I came upon the idea of using the text of the King James Version of the Bible. This is both a good test for something relatively large (compared to my sample "Overview" chapter that I was using with the initial coding, even when I programmatically repeated it multiple times for stress testing) and varied (short sections like some of the prophets and epistles, long ones like the book of Psalms with 150 parts). It's also available for use for free from places like the Gutenberg Project in simple text form. While the religious nature may be an issue for some people (as well, theologically, as the choice of it over other translations and compilations), it is also is a widely quoted piece of literature in its own right in the secular sphere and could be viewed as such. Its general familiarity, the multi-part nature, the value of search and bookmarks, and more, just made it seem like a great example to use. Also, it would make a generally available app actually useful to a wider audience than people looking for an example of an Alpha Anywhere app. It could also lead to others discovering the value of the reader technology and think about applying it to their own needs. Converting the text of the King James Version into the required JSON was pretty easy. I ended up with a straightforward JavaScript program running in Node.js on my personal computer that looked for various markers (like the start of the main text) and changes (like verse numbers changing from chapter to chapter or certain blank lines) to break up the downloaded text. That made it easy to add extra information (such as an addendum that has the required Project Gutenberg licensing information which also gave me an excuse to show off the extra levels of sub-sections that the app can handle), and also gave me sample code to give to others to start from to convert what they had. I decided to make each book of the Bible a separate main section (usually called "Chapters" in the app) and have one sub-level for the chapters of the books. I left in the headings that indicated the Old and New Testaments for those that might find that helpful when going through the TOC. I also made the decision to use the first verse of each chapter as the "summary" value. In general that seemed to work out well and shows the value of the summary feature, though there are cases where it provides little help to the skimmer. Having this large document, with all its variations of sizes of sections, turned out to be a great decision for testing. Searching is fun for people who may not even be heavily connected to the text. One of the first a person seeing an early version asked for was a list of all of the places where the word "dog" was mentioned (he's a dog lover). Looking for a word like "Moses" is a good stress test. The book of Psalms is quite long and helped surface various limit cases on some browser versions that needed to be addressed with special coding in the underlying Alpha Anywhere code. Working on multiple screen formats At this point we had pretty useful working versions that could be run in a browser or simple webview wrapper. It became clear that while this particular design was focused around a tablet screen, the actual experience was not that bad on a smartphone, like an iPhone 5. It was just that the pieces didn't fit in right. So, the next step was for Adina to specify how the app was to be laid out on a few other configurations: A tablet like the Google Nexus 7 (a narrower rectangle than the iPad) and various iPhone-like sizes. Through the use of the Responsive App Design functionality that we had already put in Alpha Anywhere (see "Responsive Web App Design") this turned out to not be too hard to factor into the app. A few overlays had to be split into two so that they could be displayed in differing layouts, and a pretty design for showing tools in landscape had to be scrapped to make a more phone-friendly version. One of the design challenges was in positioning type-in areas so that the presence of the on-screen keyboard wouldn't "break" the HTML design. Luckily, the results were very close to the original, "what would look and work best" design. This required some custom JavaScript when the input popups are displayed to respond to the different screen sizes and orientations. Further implementation The next step was adding persistence to the user data. This means remembering the user's bookmarks and history of reading from session to session. The localStorage functionality of JavaScript in a browser or browser component worked fine for this. The implementation of the user interface to access the reading history (the Frequently Viewed and Recent History lists) was done through a top-level "Menu" panel that was conceptually higher in the hierarchy than the Table of Contents. This simple list (Table of Contents, Frequently Viewed, and Recent History) lends itself to adding additional means of organization to the app in the future without needing to deal with "breaking" the carefully designed layouts of the other controls. For example, a listing by relevance to the current geographic (GPS) location of the device might be appropriate for some particular document. Dynamic Lists and the Scroller As this was going on, two new features were being added to Alpha Anywhere: Dynamic List Virtualization, and the Scroller. In database-driven business apps like those created with Alpha Anywhere, it is not uncommon to have lists of items to display that are hundreds or thousands of rows long, even after filtering. Rather than render all of the rows of a list at once before displaying the small part used on the screen, dynamic lists render only a certain number of rows around a given point in the list, and then render others on demand as you scroll, either through "More" buttons or "Drag for more" behavior. This fit in quite well with my needs for search: In a long document, a search for a simple word could result in many matches and the list of matched topics could take more than a second to render, depending on the device. Dynamic lists together with switching back and forth to top-level-TOC view of the search results, worked quite well. To go with the handling of long lists, the developers of Alpha Anywhere decided that we needed a means to quickly scroll through hundreds or thousands of items to just the item you wanted. The Scroller control implements a draggable handle that goes from the start to end of the list, displaying a message next to it as you drag showing message content from the row you'd get if you released (like a title or index). In addition, if you slide sideward as you drag, it will switch to a "fine tuning" mode where you can leave the message up and have a better ratio of finger-movement to list-traversal for getting to a desired item. The scroller was perfect for letting you move through the text as you would thumb through paper. You could move quickly to a given general place, and then slowly get to exactly where you wanted. The trick was in carefully crafting what information was displayed in the message. We ended up with the main TOC entry title, the topic title, and the summary. Getting the app out the door The final major features related to documentation and support (of the app). I added a startup "walkthrough" that Adina designed that introduces the key concepts of the app. That was implemented with traditional media-query-based responsive design to work on various screen configurations. I also implemented an "info" button for help that brought up a visual key of the main icons used in the app along with an explanation of each (again, based on her visual specifications). It also has an information panel that shows specific information about the app and the included content, such as version and copyright information. I also included the display of some debugging information, and a button to bring up a third panel with special commands that could be used, under guidance from technical support, to track down or circumvent bugs. I also added a means for saving the state of the bookmarks and reloading them on a different device to aid in making the screen shots for the app stores. At this point I was testing on a variety of devices. Anomalies on various devices with various versions of their operating systems needed to be addressed. I started using the new Alpha Anywhere functionality for building the app using Adobe PhoneGap Build and delivering it for installation on iOS and Android devices. This led to more fine tuning of the app. Finally, I created a video showing the major features in operation in a way that could support content other than the King James Version Bible, though it shows it as the example. I also started a support web site that would be needed by the app stores and for general support. As I found with other apps, one time consuming last-step issue is setting up and taking illustrative screen shots on the wide variety of devices as the app stores recommend. That's one reason I took the time to add the ability to export and import the bookmarks state with copy/paste and email. Also, it takes a bit of time to write a description, choose keywords, etc. The name for both the iOS and Android versions comes from "AlphaRef King James Version of the Bible" (in various forms to fit the field sizes allowed). We call the base application (the part that does not include the content to be displayed) "AlphaRef Reader". With all that done, I submitted the app to the Apple App Store one evening and the next morning to the Google Play Store. Within a few days, both were available for download. Once a few kinks were worked out in the listings' text, I finished this write-up and posted it. Additional thoughts Creating this app has been a great learning experience. Here are some of the things that I've found: I've always felt that the tablet form-factor, like the Apple iPad, is distinct from the smaller phones and larger, less social, devices like laptops and desktops. See "Is the Apple iPad really "magical"?" Applications can be tuned to take advantage of the screen's size and touch interaction. I found that designing "tablet-first", that is doing your mockups and thinking concentrating on only it first, as opposed to looking to something like an Apple iPhone first, gave us room to layout and figure out what's important and have a great user experience. We iterated later to fit on a phone once we found out if it would be appropriate. But, tablet was the main target, others were secondary. There has been a question about whether HTML5 (which includes CSS and JavaScript, of course) is a viable technology for mobile apps. There is also a question about whether you can use Alpha Anywhere to create HTML5 mobile apps that seemed "real". The AlphaRef Reader has shown that you can indeed make business class apps in HTML5 and that using Alpha Anywhere to create them can be a good idea. The response that people have had to using the app has been very positive. In fact, many people have commented about the speed and smoothness of operation. There have been no complaints about it being in HTML5. Helping this has been the use of PhoneGap as the wrapper to allow installation of the executables, and Adobe PhoneGap Build (as integrated into Alpha Anywhere) has proven to be a good, easy method for creating those wrappers, both during development and for final release. Reaction to the AlphaRef Reader app shows that the idea that reference material is different than books or news and there is a need for reading technology on a tablet tuned to that genre is one that resonates with many people. Many people have asked about whether it will be possible to add their own content, or other content, to a reader of this type. That was indeed a design goal. The King James Version of the Bible is just a single ".js" file containing JSON-format data that is included with the app. Including a different file in the appropriate format would change the content. Alternatively, a future version of the app may allow the dynamic loading of the data for updating or augmenting. The www.AlphaRefReader.com web site has links to further information. To install the app on an iOS device go to Apple App Store. For Android, go to the Google Play Store. -Dan Bricklin, 20 May 2014 Since there has been interest in creating other content for the AlphaRef Reader, I thought that it might be helpful to show what the bible.js file that I used for the published app looks like to help answer some of the questions. Here are some excerpts showing what the raw JSON looks like: var doc_in_JSON = [ {id:"1", title:"The Old Testament of the King James Version of the Bible", desc:"", level:1}, {id:"2", title:"The First Book of Moses:  Called Genesis", desc:"", level:1}, {id:"3", title:"Chapter 1", desc:"", body:"<p><span class='cv'>1:1</span> In the beginning God created the heaven and the earth. </p><p><span class='cv'>1:2</span> And the earth was without form, and void; and darkness was upon the face of the deep. And the Spirit of God moved upon the face of the waters. </p><p><span class='cv'>1:3</span> And God said, Let there be light: and there was light. </p><p><span class='cv'>1:4</span> And God saw the light, that it was good: and God divided the light from the darkness. ...were the sixth day. </p>", level:2}, {id:"4", title:"Chapter 2", desc:"", body:"<p><span class='cv'>2:1</span> Thus the heavens and the earth were finished, ... </p>", level:2}, ... {id:"1258", title:"License Information", desc:"The text of the King James Bible in a form suitable for use in this app came from the gutenberg.org web site and includes a license regarding it.", level:1, nosearch:true}, {id:"1259", title:"The Source of the Text", desc:"The text was downloaded from the Project Gutenberg web site and is used with AlphaRef Reader.", body:"<p>The text of the King James Bible used here comes from Project Gutenberg, www.gutenberg.org. ... </p><p>PLEASE NOTE: This License Information section is NOT included when you do a search in the app.</p>", level:2, nosearch:true}, ... {id:"1266", title:"Section 5.  General Information About Project Gutenberg-tm electronic works.", desc:" ", level:3,body:"<p>Professor Michael S. Hart is the originator of the Project Gutenberg-tm concept of ... to hear about new eBooks. </p>", nosearch:true} ]; var settings_in_JSON = {"mainTitle":"Bible: King James Version", "contentID":"kjvg10", "contentVersion":"1.0", "contentDetails":"The text of the Bible used here is from ... You may copy it, give it away or re-use it under the terms of the Project Gutenberg License included with this eBook or online at www.gutenberg.org</div>", "additionalCSS":[".cv {font-size:80%;color:#999;padding-right:2px;}", ".bodytextdiv p {padding-bottom:14px; margin:0px; line-height:30px;}"], "nextChapterText":"Next book", "previousChapterText":"Previous book", "preferredScrollerMsgLevel":0, "descIsFirstLine":true, "startingID":3};
	Writings  Home  < Previous  Next > © Copyright 1999-2018 by Daniel Bricklin All Rights Reserved.