How an interactive documentation helped me get 450+ stars on my Github repo

Brief intro:

A few months ago I made a CSS library to make navbar creation somewhat easier because most of the time you need the same things from a navigation bar:

• to look good
• to be light
• to be responsive

So I packed the most general features a navbar can have into a CSS library and put it on Github. But later I realized that reading documentation about the usage of a web component will not improve the development process of anybody. My solution was to design a trivial to use interactive documentation where the time between opening the project’s homepage and having a working code is less than a couple minutes. In this article, I will go through all the UX decisions I made to give every user a dynamic experience with my library. Here is the page if you want to check it out beforehand but I’ll include screenshots.

Does that navbar seem strange? It’s fake on purpose

If you take a closer look at the menu items on the navbar you may find them a little odd. They’re all called ‘Item’ and then a number like some kind of modern day yan tan tethera. It’s on purpose: I want it to look fake. That’s my way of demonstrating the product: by putting it where it’s meant to be and showing all the customization in real time (more on that later). However because a navbar is such a general part of a page it would go unnoticed with labels like ‘Home’ or ‘About’ so that’s the reasoning behind the item names.

Getting to the point right away

Have you ever been on a website where you were presented with a fullscreen image of an office with some mysterious quote like:

Action is the foundational key to all success.

If I want a sub three minutes experience I really can’t waste my visitors’ time on forcing them to find their way out of my motivational welcome messages to get some actual info about the library. I think mine is ‘in your face’ enough to be acceptable.

notice how I moved the actual navigation menu below the slogan

Here are a couple examples how some other (and way larger) sites do it:

Medium (upper left), GitHub (upper right), Dropbox(bottom left), DigitalOcean(bottom right)

The “How” after the “What”

Okay, so we are done with the what part, we can move on to the how. These are the two major things on the page so I made sure they are above the fold. It’s not the whole getting started guide but just enough to lure you in.

You can see this in other sites as well:

same sites as before

Halfway through text and images: icons

If a picture is worth a thousand words then an icon is somewhere around three to four hundred. While being light on the page’s size it’s also way less attention seeking than a picture would be which is very important because the content is in textual form and I don’t want to distract the visitor with some stock office imagery. So I carefully put some icons here and there.

I used font awesome btw

Copy buttons for the win

Selecting text is tedious. Pressing shortcuts is somewhat less tedious but still not quite there. Pressing a button? Oh hell yeah, I want to do that! So I included copy buttons next to the code area which copies the code to your clipboard, but they made the page more busy which meant some potential slowdown (UX wise). The solution: the copy buttons are hidden and only appear when you hover the mouse over the text area (which means you want to copy its content so indicates the right time to uncover the copy button). I also added a tooltip when you click on them as a feedback to let the user know that the code is copied indeed (it’s like a pseudo-haptic feedback).

strangely the recording software doesn’t show the cursor as a pointer on the button, but trust me it is a pointer

Those download buttons really are download buttons

I think a lot of pages handle the download buttons pretty badly. Sometimes you expect to get the files right away but got an extra page with the real download button instead. Other times you expect some kind of download page with more information about the file you want but the download starts right away without any kind of warning. To avoid that I put the file extensions on the label of the button to make it clear that the button will start a download and not just open a page.

I think the icons also help

The interactive part

As I said in the beginning of the article, the navbar has only one purpose: showing you all the possible options in a “natural” place.

The menu builder

In the menubuilder you can “fill” your menu names in so later you won’t have to look for the correct place in the documentation. The plus sign is pretty obvious for adding elements and clicking on them will make them disappear. How will the user know this? Firstly by having an infobox right above the element and secondly by putting an X on the item if you hover over it.

Option selectors

Every possible option is there as a radio button. To make it more clear I preselected all the default options. Clicking on them will change the navbar instantaneously so the users can experiment with all the options.

Code generator

It would be all for nothing it I had stopped there so I included a ‘generated code’ panel which displays the current state of the navbar in HTML and changes instant as well (and also has the copy button).

Final thoughts

The demo page is still in progress and has place for improvements but I hope I could give you some ideas with the decisions I made. If you have any feedback about the article let me know here or if you have feedback about the library itself you can leave it here or email me at [email protected].

Thanks for reading! :)