Best Practices - Updating internal documentation

Jordan Silverman

We are a SaaS startup with about 60 people. We are still in growth mode and constantly updating/tweaking the UI of our platform and mobile app.

We have found it pretty time consuming to update our FAQs, videos, automated campaigns, etc. Think Zendesk, Youtube, Confluence, Totango.

Does anyone have best practices around doing this?

Thanks in advance!

Dave Howard

Hi Jordan - a few suggestions from my years in e-learning. I've put this in a learning resource context but it applies to many categories of content.

First and most important - think bite sized whenever possible. Long form content (worst case = webinars) are a challenge to keep current. Planning your support materials in smaller 'modular chunks' that you can connect for specific outcome focused learning will reduce the burden. Think building blocks.

Secondly, be very cognizant of the format when creating content which is making use of text instructions. Video can be notoriously problematic simply because you added an onscreen title that now is outdated and could have been put into accompanying text resources like FAQ's, campaigns, etc. which are easier to update. Also critical if multiple language documentation is a current or future requirement. 

Thirdly, make sure that solid analysis goes into the planning stage to determine the likelihood that the resources will change, Often you can deliberately be more generic - block overviews of an interface or blurred interface screen shots that give enough info to locate the sharp focus core point of discussion but which won't throw the learner off because of some unrelated change to the interface. This is always a key planning point with stakeholders during project content planning. There needs to be a strong correlation between low potential to change and high permanence of the medium.

Fourth, something more akin to a Pareto principle - be clear on the 20% of content that really matters. Often as designers we don't give the content consumer enough credit for their ability to separate the wheat from the chaff. When the focus is 'how to', most folks are remarkably good at pulling what they need from well designed content. Not getting distracted by small inconsistencies. The better you are at focusing your content on quickly getting folks to the outcomes that matter to them in the moment, the more they will not notice the peripheral info.

Lastly, it may go without saying. A best practice it to make sure your content creation team has a seat at the table on some regular basis with product development and marketing. Building a connection of mutual respect can work in two significant ways. Giving your team more of a heads up about changes before they get too far down the pipe. For product and marketing, the ability to better understand the impact changes they are considering will have on customer success. I've found that CS folks can often provide critical customer impact information that will cause other teams to reconsider their initial thinking and avoid unintended consequences.

Hope there is something in this that is moderately useful. Best with your growth and happy to continue the conversation. Cheers!