Chain Core Docs
Documentation to help developers build applications using the Chain Core API & SDKs, configure Blockchain networks through the Dashboard, and reach out for support.
To maintain the confidentiality of users and customers, I am unable to publicly release personas.
Due to the closed nature of our old Blockchain product, Chain visitors did not have enough information to learn about our technology and evangelize it to their company stakeholders. Meanwhile, existing users could not build applications without high-touch support from our development team due to minimal and outdated API docs.
With the announcement of Chain's open-source Blockchain platform in 2016, Chain Core, there was an urgency to provide developers with an amazing documentation experience.
No content writers on staff
In the absence of full-time content writers on the team, we had to rely on our lead product managers, engineers, and architects to produce the documentation content. At the end of each sprint, a subsection of content was handed off to content editors, which included everyone in the company, influencers within the SF blockchain community, and leading blockchain developers.
No developers assigned to project
With the majority of our developers focused on System Engineering and building the Dashboard, I took up the task of developing the Documentation interface, in addition to designing the documentation experience on web and mobile. Using HTML and CSS, I first wrote up about ~90% of the code (navigation, page layouts, typography, color scheme, responsiveness), and then solicited the help of our Product Architect and CPO for the more complex programming logic, testing across browsers, and fine-tuning of the visual styles.
Balancing requests from Leadership
The leadership team believed early on that blockchain is a new type of product, and thus requires completely novel solutions for learning, such as interactive wizards and videos. Although I did research the value of such solutions, I ultimately fell back on the validated effectiveness of high-quality documentation. We didn't pursue the proposed complex solutions, but researching them enabled me to communicate why they weren't the right solution.
User & Audience
The main users of the Chain Core Documentation are Fintech and independent software developers building Blockchain prototypes and applications. Across sectors and teams, developers need varying levels of support and documentation material and practice different approaches to application development. Across the board, however, there was a lot of overlap in their needs:
- Comprehensive and high-quality docs to fill knowledge gaps
- Docs that fit into current tooling and workflow
- Sample use cases for various feature implementations
- Transparency around our technology, design decisions, and limitations
- 1:1 guidance, solution design and production support when there is a need for high-touch support
- Ability to directly communicate with our developer community
Having designed developer tools for years, I knew most relied heavily on easily scannable written documentation instead of interactive material. To validate my understanding, I took on a thorough effort up front to review competitors and developer-oriented services, and identify user needs and pain-points.
Organizing the information
The Documentation was being written as the Chain Core products (Dashboard, API, SDKs) were being developed, so the content was fluid and constantly changing.
Initially, I developed a very simple website where the content could be housed and used by our Chain team and customers.
It was apparent that we had to organize the content such that it allowed for growth over time. The organization of the Chain Core content was then optimized for the order of tasks and first-time to active usage. The Chain Protocol items were organized by the progression of complexity, each item building on the last.
An iterative approach to the Documentation design highlighted the need for a scalable navigational structure that could support a lot of content without becoming unmanageable.
Discovering the right user experience
Almost all developer-oriented companies have developer documentation but most take starkly different approaches to the user experience. Before designing the documentation, I first performed a competitive analysis and discovered some patterns.
The best docs gave developers access to all the resources needed for building applications and offered varying paths depending on users' depth of experience. Navigationally, these docs are designed to impose enough flexibility so users can explore and figure out what they don't know, while imposing enough structure to help them quickly find the right content when they know exactly what they are looking for. And finally, they gave users a way to engage with other developers for support.
Having a strong grasp of our user needs, content architecture, and ideal developer experience, I began to sketch and wireframe different layouts to set a direction and iterate on the best option. These early rough designs were also a cost-effective way to get feedback from the multi-disciplinary team and to validate how developers worked their way through the documentation.
As these designs were developed and with increased usage of the documentation, new behavioral patterns emerged that required updates to the design.
First, we learned that while developers did prefer to get sample codes in context, they did a lot of copy-pasting from different snippets, which could have been more efficiently organized into a single, runnable script up front.
Second, as developers built apps on the Chain Core Dashboard, we discovered gaps in the first-time user experience, which confirmed a need for a 5-minute tutorial for learning the basics.
Lastly, while current SDK docs are visually chaotic, developers’ long use of these docs has helped them develop strong intuition and recognition. So instead of creating a new SDK design, I instead linked to the standard docs for SDK, Java, and Node.
Testing the visual design
Once I had reached a set of validated layouts and flows, I took some time to create hi-fidelity mockups to create alignment around the visual design.
Some of the key requirements included:
- differentiation from other blockchain startups
- consistency with our other products, such as the Chain Core Dashboard
- consistency with brand values
I designed two versions of the documentation, one dark, and one white. Based on feedback from developers inside and outside the company, I learned that the white version was more readable, equally authoritative, focused users’ attention on the content, and was more consistent with their intuitive recognition of developer docs.
We received a lot of positive feedback from both users and the Blockchain developer community. Some of their direct feedback was:
- "Great documentation on @chain helped us create inter and intra core #blockchain transactions, both single-party and multi-party trades!!"
- "Congratulations! Chain seems like a great place to work, and all of this code and documentation is extremely high quality"
- "These docs are absolutely beautiful"
We also have 160+ active forks and 3000+ commits on Github being supported by the docs.
Some known issues were deferred due to time constraints and perceived value to users, but these need to be revisited for a comprehensive developer experience.
- Users need to have enough information about the Chain Core Dashboard before being prompted to install the application. Lack of product knowledge has caused visitors some confusion about its purpose.
- A navigation system for the table of contents that can persist in view while scrolling. The current solution of listing items at the top of the page is primarily effective for users that already know what they are looking for vs. those that need to browse or switch between topics.