July 24, 2013
It is tempting, when considering documentation, to decide that it is “someone else’s problem.” In truth, writing and maintaining documentation is a cross-disciplinary function. Content is paramount, clarity and comprehension of design determines whether the content is accessible, and information architecture will expedite learning…or frustration.
At Basho, we are proud of our documentation. All design, updates, and edits are done in the open and we encourage community participation. Recently, we launched a major refresh to our docs and, in the interest of sharing our learnings with our community, we wanted to describe some of the ideas and principles behind it.
With this recent update, we were particularly interested in a clean and legible design. We wanted a redesign that was easy to read, easy to reference, and easy to reuse.
To that end, we updated the font set to include a serif and a sans serif (Gandhi and Open Sans, respectively). Our design team selected two open source types that worked well together, but also had the best cross-browser and cross-display consistency.
We made the text larger, changed its color to be black on white for higher contrast, and limited the width of the page for ease of reading (à la Matthew Butterick’s suggestions). This focus on legibility allows us to scale content within the same design theme as needed.
As we continue updating Riak, prior documentation remains relevant and accessible. Previously, the Riak version selection was displayed horizontally, with all major releases visible. We added a selection menu that flows vertically and now only indicates the currently-viewed product version.
The navigation has also been updated so the collapse behavior maintains state across pages and links to the Help Page and GitHub repository remain static.
To appeal to our audience of both developers and operators, we now have two distinct tracks of content that are highlighted and organized in the left-hand navigation menu. These tracks are bookended by new introductory content (a slimmed-down version of “The Riak Fast Track”) and conceptual information relevant to both developers and operators.
Furthermore, since developers tend to actually write code, our examples are being refreshed to use code samples, rather than HTTP calls. This will be an ongoing process.
Where Art Meets Science
The decisions about the documentation refresh combined instinct, preference, and empirical data about usage. As the community provides feedback, we will continue to make changes to improve usability.
As with any project of this scope, many members of the Basho team were involved: our engineers who write documentation, the Docs Cabal that managed the process, and the Basho design team that provided dozens of possible designs. This distributed team was able to leverage the best of each others work to produce something beautiful and, most important of all, useful.
July 11, 2013
To learn more about what’s new in Riak 1.4, sign up for our webcast on July 12th at 11am PT/2pm ET
With the introduction of Riak 1.4, Basho offers developers new ways to leverage secondary indexes (often referred to as 2i). This is a short review of what they are and what has been added.
Secondary indexes in Riak
Values in Riak are treated as opaque, although optional add-ons such as Riak Search and Yokozuna can index the contents.
With two of the supported storage backends (LevelDB and Memory), developers can add their own indexes for querying. These can be numeric or string values, matched as exact values or ranges, and can have as much or as little to do with the stored value as the developer wishes.
Primary key lookups will always be the fastest way to retrieve values from Riak, but 2i is a useful way to label and retrieve data.
What has changed with Riak 1.4?
Previously, results from 2i queries were presented as a comprehensive list of unordered keys. Depending on the size of the result set, this could be awkward (or impossible) for a client application to handle.
With 1.4, the following features have been added:
- Pagination and streaming are available on request.
- Results are now sorted: first by index value, then by keys.
- If requested as part of a range query, the matched index value will be returned alongside each key.
Here is an example of a range query via HTTP. Pagination is specified via
max_results=5 and the return of matched index values via
In this case we are querying a small Twitter firehose data set; each tweet was added to Riak with nested hashtag values as indexes. The query is designed to match hashtags in the range
ri (inclusive) to
continuation value is necessary to retrieve the next page of results, and as expected the results are sorted by index value and key.
Where to find more information?
Basho’s docs site has been updated for 1.4: