ValidMind Developer Library

Content Engineering

I transformed our disorganized developer resources into a comprehensive reference with a clean, modern, and mobile-responsive design.

Along with authoring the bulk of ValidMind’s user guidance content, I also transformed our disorganized developer resources into a comprehensive reference with a clean, modern, and mobile-responsive design.

As a newcomer to ValidMind and the risk management space, I knew I had an advantage others did not — I could approach both our product and user guidance content with curiosity and a fresh perspective, without the baggage of prior assumptions or preconceived notions as to how things should be done and presented.

Situation

Before I joined ValidMind, our documentation site and associated resources did not have their own brand identity or design system. Along with the information being poorly organized, users did not receive visual cues when content types shifted.

Our open-source Python library (ValidMind Library) functionality was paired with our frontend application to form a complete product suite. Instead of standing alone, our developer resources were intertwined with the rest of the product documentation.

Like our quickstart portal,¹ most of the information contained in the developer resources was conceptual, not action-oriented, bombarding users with walls of text. Any helpful tutorials were buried under nested links in poorly organized sections, asking users to go searching for action-oriented information without guidance.

¹ ValidMind Quickstarts

Solution

As part of leading the redesign and reorganization of ValidMind’s documentation,² I gave the developer portal its own alternate, simplified design inspired by our checkmark logo to put the focus on the technical content:

² ValidMind Documentation Redesign

• Cleaned up landing pages with clear, actionable links to helpful tutorials and other guidance.
• Comprehensive resources laid out in a reorganized sidebar navigation, with explicit starter user journeys by role.

Comparisons

Developer Library

Before

The old developer resource section, asking you to scroll through a wall of conceptual information and hunt in the sidebar for scattered links with actionable instructions, which was also hidden on mobile devices by default:³

³ 

Previous ValidMind Developer Library Mobile View

Previous ValidMind Developer Library

After

My new developer resource portal, with a cleaned up introduction, more comprehensive resources for both relevant user roles, and important links visible on mobile devices:⁴

⁴ 

New ValidMind Developer Library Mobile View

New ValidMind Developer Library

I authored both the validation quickstart and introduction to validation Jupyter Notebook series, and edited the older developer quickstart and developer introduction into a series that paired together with the validation journey.

Testing

Before

Our old “Run tests and test suites” section, like the entry point to the developer sources, also bombarded users with walls of conceptual text before presented with an unorganized list of tutorials:

Previous ValidMind Library Testing

After

My new “How to run tests and test suites” section, with a cleaned up introduction, and relevant tutorials laid out sequentially for new users, each concept building on the last:

New ValidMind Library Testing

Features

Before

The old “Run tests and test suites” section also included all of our tutorials on features unrelated to basic knowledge on running tests:

Previous ValidMind Library Features

After

My brand-new “How to use ValidMind Library features” section, with granular tutorials sorted into tabs by topic that build on the beginner testing guides:

New ValidMind Library Features

As part of my cleanup for the developer portal, I also reorganized our source Jupyter Notebooks⁵ as how they were categorized in our source Python library repository informed how they were laid out in our documentation when they were pulled into the documentation repo to be rendered with the rest of the guides.

After sorting relevant tutorials into how_to, I wrote a Python script⁶ that automatically populated new notebooks when added to the documentation repo to this landing page in organized tabs and the related “Use library features” section in the sidebar.

⁶  Archive of validmind/documentation: update_how_tos.py

⁵  Archive of validmind/validmind-library: ValidMind sample notebooks

Samples

Before

The old “Code samples” section:

Previous ValidMind Library Samples

After

My new “Code samples” section, including several more notebooks I either authored or edited:

New ValidMind Library Samples

As part of my cleanup for the developer portal, I also reorganized our source Jupyter Notebooks⁷ as how they were categorized in our source Python library repository informed how they were laid out in our documentation when they were pulled into the documentation repo to be rendered with the rest of the guides.

After sorting relevant tutorials into use_cases, I wrote a Python script⁸ that automatically populated new notebooks when added to the documentation repo to this landing page in organized tabs and the related “Code samples” section in the sidebar.

⁸  Archive of validmind/documentation: update_use_cases.py

⁷  Archive of validmind/validmind-library: ValidMind sample notebooks

Citation

Archive of validmind/documentation Developer Portal by Beck

You can learn more about my involvement with ValidMind’s documentation and the impact I had on developer content under Technical Writing.