A realistic documentation redesign process, part1

After several weeks collaborating with our developers, now it’s online. Check it out here: http://docs.geetest.com/


Several months ago, our whole production team was working on refreshing Geetest’s website and the customer admin console. It’s a start-up company that provides cyber security services for enterprises. As a 2B company, documentation is a crucial part to connect customer companies’ developers with our products. Our primary documentation was “designed” and developed by our own developers, but this received a lot of complains from our customers. So, I was assigned to work on this documentation redesign job to implement a desirable and feasible solution.

Design process

Pain Point Synthesis

We kicked off the job by communicating with the different parts of our company, account managers, sales people, back-end engineers, and internal customer service teams. We could hear different perspectives, priorities, and needs from those colleagues (we have a very flat and open culture).

We gathered massive unstructured feedbacks and categorized them to define or confirm usability issues, which gave me some inspiration to redesign the documentation.

Here, have a sneak peak of them:

1 what’s “public ID” and “secret ID”?, and what’s the difference between “captcha ID” and “public ID”?
2 where can I download the DEMO?
3 How can I generate my own “captcha ID” and “captcha key”?

Define and Analyze

To sum up, documentation was complained because of the terrible information architecture, which includes:

1 Inconsistent language. We should use the users’ language to let them understand our documentation better and use the same term when referring to a particular action or object.

2 Unsuitable priority. A big part of the feedback from internal customer teams is about the difficulty to find the place to download SDK.

3 Confusing navigation. Customers often complained the documentation is hard to read, and many of them didn’t know where they should start to integrate our products.

Paper Prototype and Feedback

After information diverged and converged, I started to really think about the lo-fi prototype. Because of the time constraints, we decided just to draw some paper prototypes to discuss with the developers.

In the meantime, I got developers on board, and they started to rewrite docs following the same format in Markdown.

Then we sat down together, showing the prototype, making sure whether there weren’t any other unexpected problems.

Mockups and Handoffs

We used InVision to collaborate with front-end developers.

1 Created a new project in InVision.

2 Synced sketch files to this project, and uploaded SVG or PNG files to the assets folder.

3 Invited group members to the project

Then front-end developers can directly measure positions or colors inside InVision Inspect. We used the sketch measure plugin before that.

InVision Inspect

Data analysis and Iterate

All done? No!

We’ll analyze user data and improve the designs, build the new designs, and test them out again, to later define and analyze the new findings to plan out the next steps and iterate on designs.

So, how to analyze user data? Which kind of measures are used to keep track with?

I’ll be talking about it in part 2…