Re-designing Documentation Website: Planning, Content Migration, & Development

Arshabhi Rai
May 13 · 7 min read
Photo by Ben Kolde on Unsplash

As part of Solace’s rebranding, I redesigned the customer documentation website, migrated numerous content from the developer portal, and integrated a new search engine. The entire project took over six months to complete, from initial planning through to design, development, and launch. In this post, I will summarize each project phase and share what I learnt.

For anyone interested, the search engine integration is already covered in this post: Integrating the Algolia DocSearch into MadCap Flare-based Customer Documentation.

Planning

The overall project, brand and website redevelopment, was led by the marketing team. The redesign of the documentation website was a sub-project that the docs team managed. I worked closely with the marketing team and coordinated with external consultants for content, UI design, and software integration.

At this stage, understanding the roles and responsibilities, identifying the key stakeholders, and scheduling project milestones, were some of the essential items that were covered. The sooner these things are identified and understood the easier it will be to avoid any last-minute scrambling and chaos.

Pointers:

  1. Understand the goals you are trying to accomplish.
  2. Is there a specific group of people that will help you reach your goals?
  3. Make a list of tasks you may need to undertake.
  4. Are there any other web properties or sites that will be impacted by this change? For example, external repositories, client portal, etc. It’s a good idea to keep track of all your web properties, both internal and external.
  5. Are there any existing issues in the docs that needs to be assessed and improved? This would be the right time to bring those up.
  6. What resources and tools will you need?
  7. What is the project timeline?

Content Audit and Migration

The marketing team had conducted a comprehensive audit of the developer portal. Based on the audit, I developed a content migration plan, identifying all the existing content (content inventory), what would be done with it (content strategy), and where it would end up on the new documentation website (information architecture).

Hello Legacy Content

Most of the content in the developer portal was locked-up in WordPress and hadn’t been audited or reviewed for a long time. Unfortunately, there was no way to automate the content migration. While arduous, manual approach provided the opportunity to review and clean up the content. I would say that for any website redesign or content migration projects, regardless of the approach taken, it is an excellent opportunity to deliver better material on the site.

We reviewed, removed, edited, and redesigned numerous web pages. While doing so, we came across several legacy contents without any designated owners. Over time, due to changing priorities and organizational restructuring, several sections had outdated content that had long been forgotten. Previous content owners had moved to other departments, and without someone reviewing and taking the ownership, these pages by definition would be out of date. We sent out emails, and approached stakeholders, who we thought were potential owners, but our success rate was low. Eventually, we changed our strategy to a passive-aggressive approach and sent out an email stating that the content will be removed unless appropriate owners were found. And guess what? It worked! The idea was to get the stakeholders engaged and committed to own the content.

Pointers:

  1. The content audit was, I think, one of the most important task; and, equally important was to create a spreadsheet and map the old content to the new location in docs.
  2. Sometimes a passive-aggressive approach is necessary to get the job done.
  3. Ensure all old URLs are mapped to the new URLs, and keep track of the redirects, and make sure they are implemented and tested before the launch. Most users bookmark specific sites or access the links through Google, and redirecting to the new location provides a seamless experience to the user.

Website Redesign and Development

The website redesign and development went hand-in-hand with the content review and migration. Once I had mapped the number of web pages that would be migrated into docs, I started working on the wireframe and architecture of the new documentation website. I usually start by sketching ideas using paper and pencil and then work my way into incorporating the flow and logic into a structured wireframe for others to review. I use Balsamiq Mockups for developing a semi-sophisticated wireframe. The barebones design and nakedness of the wireframe help to delve deeper into the structure, navigation, and journey. The wireframe underwent several iterations, and once everyone in the project team was happy with it, I created a new development branch and started coding.

MadCap Flare

Madcap Flare is the authoring and web development tool that we use at Solace. The Flare software is an XML editor with a built-in What-You-See-Is-What-You-Get (WYSIWYG) interface. If you are comfortable getting hands-on with code, Flare offers the flexibility to customize the docs as per your requirements.

Making the Homepage Look Good

On the homepage, we wanted to highlight essential setup guides, popular topics, as well and use it as a platform for any marketing related initiatives and promotion. Using the “Docs at Glance” button users can jump directly into our extensive documentation set, or they can use the new optimized search engine. Read, Integrating the Algolia DocSearch into MadCap Flare-based Customer Documentation, where I talk about my experience with DocSearch.

Each block in the homepage is contrasted with various colour schemes, illustrations, and use of cards to highlight high-level topics, marketing-related copy, or essential video tutorials. With the Bootstrap framework, I was able to develop these layouts reasonably quickly. I did, though, spend a bit of time designing the overall flow, and creating the illustrations, icons, and custom styles.

Enhancing the Navigation

One of the biggest pain-point in our docs was the top navigation with a long drop-down menu and side navigation that would scroll along with the page. What we wanted was a fixed full-screen side navigation bar. Thanks to Flare 2018, creating the full-screen side navigation was a breeze. Their online help has step-by-step instructions for implementing fixed side navigation. One thing to note, though, is that the side navigation is automatically added on every page, including the homepage. So, if you prefer a homepage without the side navigation bar, you will have to add some custom styles to hide it.

We also introduced the card UI design to enhance the interface and user experience. The information inside each card provides a quick summary of the topic and also improves the overall presentation of the content. We implemented this design on high-level topics and in some cases in areas where we thought the material could be better presented using cards; for example, on our QuickStarts page.

Pointers:

  1. The design was updated quite a few times, primarily due to various unforeseen changes, usability issues, and corporate decisions. So, if you do go down this route, be ready for several reiterations and always, always be open to feedback and contributions from others.
  2. Whenever possible keep sending your design update for review, before you go too far down the development.
  3. Always keep your branch up-to-date to avoid unnecessary merge pains later.

Testing and Launch

With the developer portal being deprecated and a complete re-development of the corporate and documentation site, a full integrated migration test was a must.

I have listed some of the pre-launch tests we did, but there could be other tests that you may need to think of based on your project.

Redirects from the old location to new

I had created a spreadsheet with old dev portal URLs mapped to the new locations in docs. I worked with the marketing team and provided them with a list of URLs that needed redirects. For internal doc URLs and architectural changes, we tested everything in the sandbox before the launch date and re-tested it after the launch.

Cross-browser and responsive tests

I do cross-browser testing, on the go, as I add new features to the documentation site. My first go-to resource is Google’s developer tool where I check and debug any style or script issues. One of the features I like about Google’s dev tool, you will find it in Firebox too, is the ability to configure and save various screen sizes for testing. I also user BrowserStack to test browsers on Mac and iPhones.

Proofread

While it’s not possible to proofread all the pages, I had a list of new pages that were added as well as some of the legacy pages that were updated. I proofread the content and also asked my peers to go through those documents. You will often find things that need to be changed or updated to improve the readability.

Functionality check

While this is something that you will be doing as you code each feature, it is still essential to do a thorough functionality check before the launch. Once again, I asked my peers to test the documentation site. My recommendation would be to give them a specific task or area in the docs.


Final Thoughts

Whether you are developing information, curating content, designing illustration, or developing a website — yes, Technical Writers do all that — the key is to enable positive user experience. Working together with internal and external team members; for example, marketing, training, or someone from the field, often provides a different perspective, ideas, and tools that can help improve the documentation. In this project, I worked with some fantastic people in our company, and their approach, feedback, and support made all the difference in developing a good customer documentation website. Collaborate.

Solace

Publications and blogs by curious and passionate developers from the Solace community

Arshabhi Rai

Written by

Tech Writer | Web Developer | Love Beautiful Designs

Solace

Solace

Publications and blogs by curious and passionate developers from the Solace community

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade