Tag Archives: docs

Documentation – Designing for Clarity and Comprehension

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.

Design

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.

Information Architecture

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.

Basho Docs Cabal

Riak 1.4: Secondary Indexes

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.

2i illustrated

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 return_terms=true.

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 ru (exclusive).

Requested URL:
http://localhost:10018/buckets/tweets/index/hashtags_bin/ri/ru?max_results=5&return_terms=true

JSON results:

{
"continuation": "g2gCbQAAAAdyaXBqYWtlbQAAABIzNDkyMjA2ODcwNTcxMjk0NzM=",
"results": [

{
"rice": "349222574510710785"
},
{
"rickross": "349222868095217664"
},
{
"ridelife": "349221819552763905"
},
{
"ripjake": "349220649341952001"
},
{
"ripjake": "349220687057129473"
}

]
}

The 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:

John R. Daily