Start free trial Book a demo
Webinar on The Art of API Documentation: Best Practices for Writers - August 07, 2024 | 2:30PM UTC - Register Now!
migrating documentation by David

Migrating documentation: Best practices and challenges, with David Ingram, Medallia

Category: Podcast

Last updated on May 21, 2024

In our latest episode of the Knowledgebase Ninjas podcast, David Ingram, Senior Technical Writer at Medallia, discusses the best practices and challenges involved in migrating to a new documentation platform. He also emphasizes the various components that need to be addressed before initiating the migration process.

Watch the Video Podcast here

About David:

  1. David’s Portfolio
  2. He started his career as a freelance technical writer. Eventually, he got into technical writing in the software space.
  3. Currently, David is a senior technical writer at Medallia. In his multi-disciplinary team, handles graphic design, video production, and eLearning design.
  4. David became a content migration expert through the coincidental experience of moving large sets of content from one knowledge base platform to another.

Key Takeaways

  • According to David, before initiating the migration process it is important to ensure that the existing information architecture aligns with the capabilities of the new system. It is essential to assess the compatibility of reusable content and plan for mapping it from the old to the new system.
  • “When migrating content to a new platform, make a plan and fully test it on representative data. Give yourself time to handle unexpected changes and estimate how long the migration should take place and increase that by 25% when dealing with a large volume of data”, says David.
  • David believes that a documentation platform must support effective SEO practices. It should ensure clean HTML for Google crawlers, support mobile content resizing, and users should have control over the metadata and access to robot.txt and sitemap.xml files.
  • He adds, “Analytics is another crucial aspect in any documentation platform as it identifies the top-performing articles, the same structure can be replicated in other articles. Leveraging simple automation using JavaScript or Python can streamline repetitive tasks including cleaning up the unnecessary style tags in HTML.”
  • “Technical debt in software development refers to using outdated systems due to time constraints. Small teams often struggle to update the old content, but migration provides an opportunity to eliminate repetition, condense content, and avoid keyword cannibalization. During our latest migration, we reduced 40% of our content without missing any information.”
  • It is easy to divert external clients to the new documentation portal, but it becomes difficult to fully communicate and socialize the change internally. So, it is necessary to communicate early about the migration to the internal stakeholders and emphasize the benefits that they will get from it”, David says.

Also, Check out our blog on Migrate Your Knowledge Base Articles Without Affecting Search Engine Rankings

Rapid fire with David Ingram

  • Highly recommended resource

Journal and magazine of the Society for Technical Communication (STC)

  • One word that comes to your mind when you hear documentation

Cozy

  • A piece of advice you would give your 20-year-old self  

Don’t be afraid of personal creativity in writing

Subscribe to Knowledgebase Ninjas:   

  1. Apple 
  2. Spotify 
  3. RSS 

David ingram quote

 

 

 

 

Gowri Ramkumar

Feb 20, 2024

The Art of API Documentation: Best Practices for Writers

Related Articles