dariofigueroa

SDK Documentation

Role: Designer, Developer, Copywriter

Alongside two other interns we completely rewrote and redesigned the existing Showpad SDK documentation from the ground up.

Back to HomeView the Site

The Problem

The pre-exisiting documentation was largely incomplete and unrefined. Though the bare bones were present, it was still a lot of guess work. The documentation seemed more directed towards veteran developers, full of technical jargon and missing steps.

Our goal was to fill in the details and construct it in such a way so that anyone would be able to parse the information. We were largely inspired to write it out this way after seeing a tweet by @lindadong on writing documentation.

The Users

Our primary audience reading through the SDK documentation are seasoned developers looking to adapt the Development Kit to suit their business' sales needs, someone who knows what their talking about and at the bare minimum understands the fundamentals of programming.

Though that might have been our primary audience, we wanted to make sure we focused just as much on our secondary audience, people who have no idea what they're doing, people with little to no technical know how.

The Process

Copywriting

Before moving into any of the design work or even the code, we wanted to know what we were going say before worrying about how it was going to look.

The engineers of our team began the copywriting process by compiling a bulleted list of the step by step process necessary to launch an SDK application. We then took that more technical and stoic list and rewrote into something more human, more layman.

The final part of the copywriting process involved no copy what so ever, as we decided to also include in the documentation screencaps and videos detailing the process in a more visual way. We went through the SDK process ourselves and along the way gathered various recordings and stills of our screens and put them along side their text counterparts in hopes to add another layer of accessibility.

Initial Sketches

The design process began by using Invision's Freehand tool, where I quickly drafted out two rough versions of the site, where the most notable difference is that one had the navigation running along the top of the page and the other had the navigation working as a persistent sidebar.

We moved forward with the sidebar version of the site as we came to the realization that there would be a large amount of links to various parts of the page and using the top navigation would involve using dropdown menus, which we wanted to stray from.

After having made the decision of the overall layout, we quickly made note of some improvements that could be made to made the content easier to understand and more visually exciting and bluntly, a little less boring.

We had the idea to include captions to the images in order to reinforce the point we were trying to teach make the screenshots even easier to understand. Furthermore, we had the idea to add a 'cool looking thing' at each new step, making the content more bearable and further reinforcing our visual hierarchy.

Typography

The typographic decisions were again made from a stand point of accessibility and legibility. As such we opted to build the site using the 'System Font' font stack, detailed more thoroughly in a Smashing Magazine article.

By utilizing the system's fonts rather than a web-font provided by Google or some other service, we accomplish two things. We remove another source of latency and thus load in our page faster, but more importantly, we create a more native and more familiar experience, encouraging users to stay on the page.

Colors

In the same vein the colors chosen for the site were chosen based on accessibility and ease of access.

The color blue has psychological connotations to qualities like 'credibility', 'calming', 'clean and focused', all traits we were striving to reach.

After deciding that we would be using blue as our accent color for interactive elements such as buttons and links, we reduced the rest of the palette to black, white, and a few shades of gray to keep the clean and focused feel.

The Result

After the design was largely finished we moved into the code, utilizing the Bootstrap framework alongside custom HTML, CSS, and JS, we finished writing out and documenting the Showpad SDK. See the final product.

Back Home