The great divide, part 2: Implementation - By Scot Hanson

(Editor's note: This is the second post in our two-part series on copying and updating an existing knowledge base for a new software release. See The great divide, part 1 for additional background and explanation.)

You know you’ve got great software tools when they make you look good in front of your supervisors. For the aACE Software 2022 help guide migration, KnowledgeOwl did exactly that.

As Kate noted in her previous post, we had migrated to KnowledgeOwl before. Importing the guides was easy, but the overall process of updating the knowledge base (KB) was long. For aACE 6, we opted to create a separate KB, knowing that it could be a long process to convince all our current customers to give up something great (version 5) in favor of something awesome (version 6). But we wanted all users to have relevant guides and we wanted the new KB ready with the software release. 

To that end, we hired two additional writers — Amelia and Elisabeth — as part-time summer interns. They signed on to help test the v5 guides against v6 functionality and make changes as needed. I felt worried about coordinating the work, so I made one of the best decisions of my career and asked Kate for advice.

(KM: This post is all Scot's own work, aside from the occasional parenthetical aside from Kate, set off like this. I'm also not sure my advice was truly worth this much. 😉)

Kate has summarized the overall approach that she recommended and we implemented. What follows is a recap of lessons learned during the migration process, taken from notes I jotted down through the summer. Caveats:

• I’m not normally this reflective about work — the notes were directly linked to this collaboration.
• I usually took notes when we stumbled into a snarl and had to untangle things.
• I’ve edited the notes extensively, increasing clarity (I hope), but reducing the feeling of improvisation and discovery.
• By August, the migration project had settled into a steady routine, so the note-taking dropped off sharply.

Additional Aspects of the Migration

Before the migration project started, I had noticed some fuzziness in our screenshots. I collaborated a little with KnowledgeOwl support to get better visual results, changing my screenshot process to edit in Snagit.

I documented this new process for the interns. Then I continued that momentum to systematize help guide updates. Having these instructions made a notable difference in getting the interns up to speed.

June 08

As the first stage of the migration process, I upgraded our account with a second knowledge base, copied the knowledge base to get all 430 guides from the v5 KB into the v6 KB, then set the status and tags in v6. KnowledgeOwl made this almost effortless. It was a little scary, actually, to see how easy it was to upgrade our KnowledgeOwl account. With the click of a button, I could have a dozen knowledge bases at my fingertips. The power!

A quick review of the migrated help guides showed a number that were internal-only documentation or still in Draft status. These didn't need updates. I exported a KnowledgeOwl report of v5 guides in Draft status, then tasked an intern to go through them in v6. She cross-referenced the v6 KB Manage Articles screen, changing the status back to Draft and removing the review tags. That left us with 411 guides to migrate.

(KM: We probably could have avoided this pitfall if we'd been more selective with the bulk edit to set everything to Ready to Publish. If we'd created a filter first that looked for only Published statuses, and then done the bulk edit by selecting all of those, we'd have left the pre-existing Draft guides alone. I should have included that in my recommendation. Whomp-whomp.)

My supervisor recommended creating a project schedule. I used a Google Sheet shared with the interns. This took the place of Kate’s suggested, more efficient use of Manage Articles filters. It involved duplicating some info, but it also allowed me to re-organize the sequence of guides (as noted below).

Despite that structure, 400 help guides felt a bit intimidating. To help eat the elephant, I divided that number out across work days from June to August. Factoring in ramp-up time in early June and various summer vacations, our team would need to review and publish seven guides per day.

I felt we needed a more detailed project schedule than that.

First, I tried adding in the category/subcategory structure of the KB. We had 88 categories and subcategories, which each contained 1-18 guides.

But that replication of the KB structure felt a bit hodgepodge. To organize things more, I identified top priorities, focusing on important topics that included higher numbers of guides. This approach meant we would be attacking the longest, most complicated guides first.

Then I remembered an important detail: two of my three writers were interns. 

Our summer interns were brand new to aACE and only had limited experience with technical writing. Throwing them into the deep end with the longest, most complex guides didn’t sound very effective.

Starting with shorter, simpler, lower-priority articles seemed like a helpful training ground. It could give the interns a feeling of success, and rookie mistakes wouldn’t impact the higher-priority guides. Since one of our company rules-of-thumb is to first address low-hanging fruit — an informal use of the Pareto principle to guide decisions. And I decided the easiest way to categorize all 400+ guides was by word count.

June 09

Reorganizing the guides by length carried over to the next day. To get some sharper minds to help, I submitted a feature request to KnowledgeOwl for adding word count functionality. They took the idea into consideration, so we’ll see what happens there. 😉 But in the meantime, I still needed word counts.

Happily, there are websites that easily handled the counting.

I first looked at WordCounter.net, which gave a very accurate count, including an analysis of keyword density, an estimated reading level, and a predicted reading time. (The site also provides tools for tracking how much leaner your writing gets as you edit, plus a fun random-word generator.) However their Web Page Word Count tool only counted individual pages. I didn't have time for that.

Next I found Wordcount.Weglot.com, which seemed to offer a website-wide count. I tested it on the v5 KB, but the pages-and-numbers it returned didn’t quite match my expectations.

I compared the Weglot results for several pages against the WordCounter.net results for the same. The negligible differences between each counter were encouraging, but at the same time I felt confused.

Both sites returned a really high word count for the short guides I tested. Some research showed that they weren’t counting the human-view, but the computer-view of the HTML. So as long as I didn’t have any guides with tons of coding in the background, the word-count sequencing would be fairly reliable. Thanks to KnowledgeOwl’s approach to styling, I was very confident that this would work.

I organized the Weglot results of our v5 KB in a spreadsheet, again using Google Sheets because I wasn’t doing any complicated calculations and it would be accessible to the interns in-office or during telework. I deleted most of the info Weglot provided, keeping only page titles and total words.

With a little massaging, I had a list of guides complete with word count. I sorted that list by ascending word count (for the low-hanging fruit), then added a column for each intern to 'claim' a guide and a column for comments:

Sample of our Google Sheet at the end of the migration

Then we got cooking.

Initially, all three of us (the two interns plus me) updated guides. They would send their work to me for final review and for updating the Status to Published.

But I quickly discovered they could review the short guides faster than I could answer questions, review guides, and click Publish. My role soon shifted to focus only on reviewing, while the interns were off to the races.

(KM: This combination of Manage Articles exports with an external data source was smart. Word count as a proxy for complexity is an interesting approach, and one I've not seen used before.)

June 13

Kate mentioned the eventual need for a guest blogger bio — it started to sink in that I was on the hook to try and share something useful.

(KM: This describes my feeling of angst every time I realize I need to work on another blog post!)

June 14

Mid-June brought the first couple hiccups in the actual migration process.

We found that copying the help guides into the new KB did not update the URLs for internal links.

While KnowledgeOwl provides helpful tools to simplify cross-referencing, I had opted for regular hyperlinks for the convenience of being able to look at the link and see the full URL right there. But now in the v6 KB, these old cross-reference links to related guides were returning a 404 error. (In contrast, links to external websites for our integration partners were just fine.)

Happily, copying the guides like we did meant that these internal links were only one digit off. We identified that the interns only needed to change the 5 in the URL to a 6.

But just updating the URL didn’t fix everything. We realized that putting all the guides into Ready to Publish status had the curious side-effect that they were now unpublished. I updated my review process to manually check each cross-reference link for a 6.

Update from October: Now that most of the guides are back to Published status, this issue has gone away. The only difficulty is that I’m now in the habit of checking URLs instead of just clicking the links. 😅

(KM: We have three different "Draft" statuses: Draft, Ready to Publish, and Rejected Draft. In this case, since Scot had bulk-edited all articles to the Ready to Publish status and was then setting them to Publish to signify completion, most of his cross-reference hyperlinks threw 404s when he did his review, since they had not been reviewed and published yet.)

June 16

Another consequence of having two KBs with nearly identical names emerged: confusion.

I jumped into a guide to make some revisions that we wanted users to be immediately aware of. After revising the content — and agonizing over whether a sub-heading, a bullet list, or a chart were the best way to format it — I clicked Publish. Then I realized that I had been working in the v6 KB. 

Update from October: This has continued as an intermittent problem. I’ve coordinated with our graphic designer to change our company logo in the banner to a help guide version label. This makes it much easier to differentiate between the two KBs.

June 21

We encountered an odd issue with KnowledgeOwl redirect links.

Part of the interns’ revision checklist was to look for ways to make guide titles more clear and concise. However, one of these updates actually reverted a title to match an existing permalink in the Old Links pop-up. The intern was able to save her changes. But when I tried to publish the updated guide, KnowledgeOwl validations stopped me.

After I identified where the error message was coming from, I made a butcher-block modification and deleted the old redirect link. Fingers crossed that this doesn’t come around later to bite me. I’m planning on running a link check on the entire site when we call the migration 'complete'.

June 22

A small complication arose from sequencing the guides by low-to-high word count.

Some short guides the interns worked on early presented concluding steps in longer processes. An example of this was the process for submitting expense envelopes for reimbursement. The final guide about generating the disbursement came up on the list before the longer guides about entering expenses and getting them approved. Our word count approach caused difficulty because the intern hadn’t seen the intro content or learned how to handle the data needed to test certain functionality.

This was aggravated by the fact that I hadn’t looked at some guides in months or years. When the interns raised questions about functionality, I sometimes had to go spelunking myself in order to figure it out.

Since this issue was very guide-specific, we couldn’t modify our process to address it. However, Amelia and Elisabeth were smart and resourceful. Once we identified the problem, they were able to recognize other instances, do the needed research to brush up on a feature, and push the update through.

At this point, I also stumbled upon a tangential detail of KnowledgeOwl that really impressed me. I asked their support staff some awkward questions about money, and they explained how their pricing structure allowed us to add users for as long as we needed them.

And also remove them as needed.

As soon as the interns didn’t need editor-access, we could deactivate those seats. aACE Software is growing, but we're trying to be cost-conscious. This KnowledgeOwl policy is way better than most other tools I've seen (e.g. where buying a seat costs you for a calendar year). It’s not a detail relevant to the migration project per se, but I just like partnering with a company that really focuses on supporting their users.

(KM: Scenarios like this are exactly why we set our pricing policy the way we do, so we're happy this ended up being such a perk!)

June 27

Managing interns forced me into a paradigm shift. Previously in my career, I had avoided what I thought would be dreary, stifling 'management' responsibilities. I was a writer. A creator. But in order to coordinate effectively with the other writer-creators now on the team, I had to do management stuff and make plans, then deal with it as my plans encountered reality. 

A significant example of this came from the idea of having 'summer' interns. I had planned for their workload to extend June to August. However, after two weeks of focused work, the interns had the migration 25% complete. I’m terrible with maths, but even I could recognize that their pace meant we would run out of migration before we ran out of summer.

My supervisors alleviated my anxiety about possibly doing a bait-and-switch with the interns — hiring them to do Project A, but then assigning Project B — by encouraging me to think long-term. The month that the interns had spent learning how to navigate and work in our software made them valuable assets.

They recommended having the interns work on other tasks and start thinking about continuing to work for us when school started up again.

June 29

I realized another use for the KnowledgeOwl publishing status options. On some guides, we were able to quickly update the text, but the software screens weren’t always ready for screenshots. So we moved these guides to Draft status. This segregated them from the migration lists and the published content. We kept notes in our project schedule spreadsheet about these guides.

Update from September: The interns have started to loop back to these guides. As we’d hoped, many of the screens are now ready to be shot, framed, and published.

(KM: In this workflow, I also recommend using tags that explain why the guide was in Draft status, such as 'update-screenshots’ or 'waiting-on-final-ui'. This would give some more detail in the Manage Articles export if it was being used, but even without it, this practice makes it easier for any writer to open the article, check the tags field, and see what the guide was waiting on. Plus it adds the satisfying feeling of removing that tag once you’ve made the updates. Who doesn’t like a little extra dopamine?)

July 12

By this time (the rough halfway point of summer), I felt I was relying too much on relegating tricksy guides to Draft status to review later. I didn’t want to get to the end of the summer and have a ton of guides that still needed serious attention. 

I started trying to send more revision notes back to the interns. This also helped get me away from the efficient (but ineffective) habit of just fixing things that the interns missed. Training the interns to become better tech writers seemed like a valuable long-term approach.

For this approach, I wanted the interns to easily spot my comments, so I used the text highlighting tools. Unfortunately, after logging a few dozen notes to interns, my patience dwindled at how many clicks it took to highlight a line of text in the editor. I would have loved the ability to change the text background color with a single click. (But it’s possible that I should have just come up with a better convention for annotating articles.) We also had to establish a convention for framing highlighted comments in brackets. Otherwise the current highlighting got applied to the next person’s comments.

(KM: KnowledgeOwl doesn't have the best tools for this collaborative workflow. Based on this conversation, I added Scot to a feature request we have for in-editor comments similar to what Google Docs provides. If you're interested in this feature, please let us know!)

July 13

All the Draft status guides weighed heavy on my mind. No apparent solution. 😓

Another issue arose from a short conversation with one intern. She brought up questions about how the other intern had used Snagit to create numbers to identify sections of a screenshot. We muddled through the specific issue.

But the larger complication was coordinating work and maintaining consistent standards when we weren’t all in the office at the same time. I wished that I had set some expectations about referring to the style guide more frequently and even improving it as we went.

July 20

This far along, we frequently came across guides that interns couldn’t easily test. These were advanced topics and complicated workflows, such as processing sales commissions or completing inventory audits. 

I assigned these guides to myself, but those darn interns didn’t slow their pace. My treading-water approach, as you might have guessed, was Draft status and a note on the spreadsheet for attention later. I internally debated whether that was foolish (because August might become a serious crunch) or wise (because the software was becoming more stable with bug fixes completed and finishing touches applied).

Similarly, I was still struggling to just highlight areas for edits and kick guides back for revision. Marking the edits felt like as much effort as making the edits. I had to keep reminding myself that the tech writing training was as important as getting guides published. My long-term hope was that eventually the interns would be able to help tackle all those guides in Draft status. 

July 26

At the end of July, I needed to give a short summary on the project at our management meeting.

With some effort, I found that the numbers showed that we had reviewed ~70% of the titled guides, but only ~60% of total word count. Plus we had 31 guides with outstanding tasks. (Looking at you, Draft status.)

July 28

Two-thirds through the planned time frame, I chatted with the interns about how they felt things were going.

One with experience in a college writing center viewed our process as a typical revision process.

However, the other intern had not had a similar experience with collaborative writing. She mentioned that when I sent guides back with comments, it felt vaguely like a rejection of her efforts. We discussed some ways to help shift that perception, framing the process as more of an ongoing conversation than a pass/fail grade. (And I also made a note to be mindful of positive communications.)

We also realized that one intern had found a quicker way to update screenshots, using the Replace Image feature. However, this method was also preserving size reduction settings from the earlier screenshot, which caused trouble when combined with our Snagit-based image update process. A short discussion clarified the issue and how to avoid it.

At this point, I also started to see results from an ongoing effort to establish a conversation habit of contextualizing questions.

Earlier in the migration, interns would just ask for help and point to a paragraph in a guide. Because I was coming from a completely unrelated activity, my initial answer was usually, "I have no idea." After trying to consistently ask them to clarify which guide they were working on, they started to independently provide that context info before they asked their questions. (Yay!)

September 01

The 'summer' internships have technically finished.

During the last two weeks of August, we were assigned to shift focus to another project for online learning resources. This affected the help guide migration, as you’d expect. 

But the product development had also continued past the August timeframe. The deadline, as deadlines are wont to do, had shifted. So the migration was not officially concluded.

We still had 10 guides not reviewed at all. And these were the longest, most complex articles in the KB. Plus my backlog of guides to review had been eclipsed by the online learning resources, leaving approximately 40 guides noted for follow-up. 

On the bright side, the interns had been diligent in moving through their work. They did such a good job that we invited both Amelia and Elisabeth to carry on as part-time contract workers while they're in school.

And I had the fun side-project of writing letters of recommendation for them.

October 03

We’re still working on putting all the guides to bed. The learning resources eclipsed things again.

At the end of September, I received an exciting email from Marybeth at KnowledgeOwl. She explained that they had developed and released a new tool to "verify link happiness" in a knowledge base.

This was great news. I had been using a pair of third-party online services to check the KB links — cumbersome, but an important QA step.

I tested the KnowledgeOwl native tool and found it’s not only much faster, but it gives a much higher confidence level about what is and is not being checked. Plus it’s tons easier to run. 

Thanks again, KnowledgeOwl, for making my documentarian life more pleasant!

(KM: Thanks, Scot! We're still finessing the Broken Links Report, but it was our most-voted feature from our 2021 annual customer survey and we're excited to see that it's proving useful for folks.)

Conclusion

Looking back on the migration project, I’d sum things up by saying the project did not conform to my project planning, but it was a success.

Some aspects turned out better than others. For example, as I mentioned earlier, I wish that I had framed things in a way that we could have evolved our style guide as we applied it to user guides. And despite some complications with the word count spreadsheet, I have been very pleased with having our work organized this way. I’ve continued to use that list even as the migration project is winding down.

As things stand now, a majority of the v6 help guides are ready for use, with a certain amount of chores left to do before I can report that 100% of the guides are published. But that 100% is an idealized number — there’s also a back-log of guides that were in process when we kicked off the migration. Plus another back-log of additional info from the software developers that we need to mine for additional user support information.

The fact that the migration went as smoothly as it did is directly tied to KnowledgeOwl tools that are easy to implement and astonishingly effective, as well as superb counsel from the KnowledgeOwl support team.

Because KnowledgeOwl is what it is, I felt comfortable hiring two brand new users. And I didn’t feel too surprised that they were productive in less than a week. Because of that, I’ve been able to give distinctly positive reports to my supervisors throughout the process.

In short: Thanks, KnowledgeOwl, for making me look good.

(KM: Scot, the credit for this lies entirely with you and your team. This kind of major content audit is daunting and tricky; we're glad to see that KnowledgeOwl seemed to help rather than hinder the process. Thank you for your candor in sharing the ups and downs with our readers!)