A UI Audit of LiveAPI Create Docs Page

My team and I am working on LiveAPI, as a highly automated to API documentation tools such as Swagger/OpenAPI (see our Swagger Alternative page for the specifics).

In this post, we will do two things:

1. Learn about the capabilities available in the "Create API Docs" page of LiveAPI
2. Do a UI audit, list the present weaknesses and set some aspirations for future improvements

How the "Create Docs" Page Looks Like

As of writing, the "Create Docs" page looks something like this:

The page provides a number of capabilities within a single view:

Set Project Scope

Set the scope for a newly created project. A fresh LiveAPI account ships with a personal scope by default. If you're a pro account owner - you get the capability to create organizations (or teams). And you can add upto 25 people to this organization, and share projects with them automatically.

Load Public Git Repo

The easiest method to test out LiveAPI is to use the "load public git repo" feature.

In this method, all you need to do is, goto a public git project (such as NodeBB) and copy its URL.

Connect to Github, Gitlab, BitBucket and Gitlab Self-Hosted

The next section is ways to obtain read access to repository listing in various popular git hosting providers.

We support the top 4 in most popular hosting providers which are:

1. github.com
2. gitlab.com
3. bitbucket.com
4. Self-hosted gitlab

UI Audit - How We Plan To Improve

Within our organization Hexmos, we think about design as follows:

The heart of design is priority. Knowing what's important is in itself the most important kind of knowledge.

Why is priority the most important aspect? Because it guides the eyes on a given canvas.

Priority defines the sequences in which the eyes move across a canvas.

The existing priority

Since these are the early days - we have been super busy with getting the functionality out - we still have not prioritized the UI correctly.

As you can see, now the expected eye movement is totally all over the place, with multiple focus points, and confusing set of disorganized buttons.

We are compelled to fail ourselves in this UI audit - but that's alright - we're all about continuous self-improvement.

PNDCC

The way we tend to improve our design is via the PNDCC rule. We do these things in order:

1. P - Prioritize: Prioritize all the existing elements based on the desired order in terms of eye movement.
2. N - Negative Space: The element with the highest white space around it gets the highest attention usually. So once we have the list of elements by importance, the most important element gets the highest negative space around it.
3. D - Dimension: A more obvious rule - the more important the element - greater the space it must take
4. C - Contrast: Greater the foreground color differentiated from the background color, higher the prominence of the given UI element
5. C - Color: Brighter the color, higher the prominence of the given element (bright yellow takes more attention than mild gray)

Applying PNDCC

The most difficult task here is to determine the priority of items. Once that is done - we can easily get a highly functional UI redesign for this design problem.

Prioritization requires a broader kind of thinking - here we consider - what is the task really about and what should the customer experience be.

In our case - we will divide the customers into two types:

1. First-time customers (who probably want to trial the software with a public repository)
2. Returning customers (who probably want to connect a git provider account or use an already connected one)

What the above categorization tells me is that - I will need two visual blocks - separated via good amount of negative space.

First caters to "first-time customers". The second caters to "returning customers".

We could have more intelligent, dynamic pages here - but for now - I think some basic graphic design can solve the problem for us, so we are happy enough with that.

In the first block - we will mostly have the "public project" section.

In the second block - we need to find a way to properly organize/prioritize the right git provider for the given user.

The second block is more tricky - because - there could be many providers, with slightly different attributes, such as:

1. There is gitlab.com but also self-hosted Gitlab
2. For each self-hosted gitlab option - you can connect to multiple usernames
3. For bitbucket option - you can connect multiple usernames

If I were to put it in a hierarchy, this is what we have now:

Private Git Providers
    Github
        User1
    Gitlab
        Gitlab.com
            User1
        Self-Hosted
            User1
            User2
            ...
    Bitbucket
        Bitbucket.com
            User1
            User2
            ...

Since - we cannot think of any given provider as more important than the other here (except maybe by user count, etc - which I think is too much of an arbitrary parameter in this context) - I think we have to resort to some simple "grouping" first.

We could have some sort of larg-ish icons and text for the three major options:

1. Github
2. Gitlab
3. Bitbucket

With these more prominent icons, we can create "lists" under those.

Here we can list any subcategories - if any such.

So this way - we can grab attention to a particular part of the screen which is relevant to user first.

Then - we can guide them to the more nuanced option further down the line.

The intermediate result of the analysis

From our prioritization efforts - we end up with something like the above. I'll continue the analysis in one of my future posts. To receive updates on how I proceed to solve this problem - from design to implementation - please do follow my account here, or @shrsv23