Event Summary: Documentation HubSpot Admin HUG with Nicole Pereira

The HubSpot Admin HUG (Hubspot User Group), hosted by HubSpot Evangelist Kyle Jepson, held an event on "How to Create Exceptional Documentation," featuring Nicole Pereira, Founder of Remotish and Culturish. Nicole and I built the documentation and knowledge management processes & program at Remotish, so this seemed like a good choice for the first educational event summary on this topic on the blog!

• How to start documentation with one sentence
• The different types of documentation
• Living documentation
• When not to document
• How to keep documentation human

Introduction

According to Wikipedia, which is a large depository of documentation itself, documentation is any communicable material that is used to describe, explain, or instruct.

Nicole said documentation can be fun and not scary, and hopefully this event helps make that view possible.

She explained how creating and maintaining documentation gives you the freedom to take time off, promote, and other experience benefits.

Starting documentation with one sentence

• You don’t need lots of planning, outlines, and goals before starting. That could be daunting. 
• All you need to start your documentation is one sentence: “Info on (topic) coming soon”
• Communicating to your team about what you plan to write about gives transparency and real-time planning to the people who will use the documentation

Types of documentation

1. Educational - focused on learning, not immediately used:
   1. Trainings, theories & concepts, historical record
   2. Example: company culture guide
2. Process - focused on conveying a specific order of things to be done:
   1. Step-by-step guide, user manuals
   2. Example: standard operating procedures
3. Data - focused on storing and relaying data:
   1. Important dates & numbers, glossaries, links
   2. Example: salary scale

Mixing types of documentation into one article can be confusing or distracting. A better method is to add interconnecting links to separate articles for each purpose, so people don't get distracted from their true purpose or question they are answering by reading the documentation.

Kyle said his goal is teaching everything you might want to do in HubSpot, but a company may want their team to know how they use HubSpot. HubSpot admins stand in the middle of these two goals, filtering out the noise of all the possible tools and ways to do something into the business case and strategy needs.

Living documentation

Documentation is not static. Keep it alive:

1. Focus on constant iterative micro updates vs. occasional macro overhauls
   1. This is where people avoid documentation. They think it will take too much time away from work, but if they do it iteratively, while they are doing that process or adding new data, it is not a huge amount of extra time or a large project. They become a person with a habit of documentation instead of avoiding it.
2. Assign owners of documentation categories or articles, distribute the responsibility to help with updating & adoption
3. Use a system with a change log or date of last editing, to trust the info is current 
4. Announce updates to documentation in other communication channels (Slack)

When not to document

When you build a culture of documentation, there are some things you may not want to document.

• Information that is changing rapidly (daily) - if dated or misinformation can be harmful, direct people to a knowledge holder instead.
  • Example: billing systems are changing, so giving the incorrect bank account would be harmful
• Personal or sensitive info - databases of customer or employee info should be secured in proper systems.

Keep documentation human

Make it accessible for all levels of knowledge & language skills. 

1. Limit jargon (or define it with a glossary)
   1. Example: Does MVP mean most valuable player, minimum viable product, or another phrase in this context? 
   2. In the chat, Adam Stahl said, "Limiting jargon has been a huge benefit for me, inspired and policed by Jen Bergren 😁. Especially with different stakeholders that may have different meanings for the same abbreviations." 
   3. Kyle said HubSpot has a culture of acronyms that change, and people can become numb to it and don’t realize they are doing it. Now, in team meetings at Hubspot Academy, one person is in charge of defining jargon during meetings in the chat.
2. Don’t be too technical
3. Avoid complicated writing. Simplistic language is better, such as using an 8th-grade reading comprehension level.
4. Use structured formatting (subheadings, bullets, and more)

Questions and answers during the event

At the end of the event, the open discussion included:

Clayton Sardella: Not to jump the gun, but will we discuss the best way to get the information to the team used to create these types of documentation? (Examples: PDF, Word, Powerpoint)

• Using a wiki-based system, with a change log when things are updated, and use categories
• There is a difference between a bunch online html directory files and using a content management system with containers and version control
• PDF and Word are not the best documentation engines, they don't create a collection of info linked together in an easy way
  
  

Clayton Sardella: For the owners of the documentation, keep those to leaders/managers or let individuals be owners of the documents?

• Let individuals be owners, distribute the weight of knowledge
• It is a great training mechanism -- when you have to tell someone how to do something, you learn more about doing it better yourself
• Some people own 1 article, some own categories
• Create career paths forpeople owning knowledge and process of how work is done
• If one person owns it, they have to run around to bug people who have the knowledge -- which helps them learn
• Everyone should be a participant to document their knowledge
• If you're a business owner, if you don’t document it, no one can do the work
• Selling a business is not selling people or product, it is selling the way it is done, the way it is made, the way people behave... you need documentation or you can't sell
• If you want to get a promotion, but no one can do your current job, you may not be promoted since no one can do the job. If you have documentation, you won't need to train someone for so long, to take over your old job.
• If you take a vacation, someone can back you up for a week without stress about or during work, using documentation
• Dealing with life, but worrying about keeping employment, is the worst. A documenter of 1, the one person with all the freedom, can hand it off to someone to take care of vacation, etc.

Documentation = freedom

Wendy Kolber: I tend to be a saver. Is there any reason to save "expired" documents? (i.e. dated documents from a previous year, like holidays or pay period dates, etc.)

• In a historical situation, you can link off to it, 'here’s what happened last year'
• "Here are the old mission vision values, here’s what it is today,' it can be referenced still
• A change log provides value
• But don’t become a hoarder for everyone/everything else
  
  

Taylor Ruhle: Do you have any thoughts around the balance of text to video links within process documentation? I'm a very visual person so, video feels more helpful to me than a chunk of text.

• You need all three since everyone learns differently: photo, text, and video
• The same in multiple formats, so the user can choose video or written
• Kyle says a different team does videos and articles. It's hard to make engaging videos out of something like a list of contact properties. Video is better for showing how to click through something, than writing.

  • Kyle says maintenance costs on HubSpot videos are rough, to keep up to date.

    It's why he likes Linkedin, the videos disappear after a while and they don't need to update them.

    In HubSpot Academy, the video has to be re-recorded.

    Written documentation is easier to keep updated, you can edit faster.

• Jennifer Nixon: Totally agree, I don't want a quick video of something I can skim as a list
• Taylor Ruhle: In the past, I'll break the video up into sections....because I learned from re-recording a 7 minute video too many times haha
• Adam Stahl: When recording a video, consider also getting the transcript for it as a jumping-off point for a written version of it.
• Clayton Sardella: I follow a 3-point method for documentation.

1. being the first communication (email, meeting, phone call)
2. A written document for people to refer to that is in a simple form (bullet points and pictures)
3. Doing a video of how to execute the process or documentation and linking it to the written document

• Kristeen Romero: I love adding gifs to make things more interesting

Aurora Klok: I know one of my issues is I try to get into a lot of detail with my training and process documentation. Do you have any good methods to use when deciding how to decide how much content to add?

• Be iterative. When the document started, it was a sentence, then after a while, you may need to split it into 14 new articles with a table of contents. Making sure it is constantly edited is better than worrying about details right away. This helps make sure people are documenting at all, as something you do every day instead of once a year or month.

Claudia Encinas: How to keep track of internal documentation when processes change and even employees change? Who should own that?

• Assign someone as a knowledge holder 
• You should have a process in offboarding to pass ownership of it to someone else or to a manager
• A backfire situation could be if you get too good at documenting and not good at updating, people start to not rely on the documentation since it is not up to date. You can remove or sunset documents.
• Make sure the most-often-used processes and things referenced often always updated
• Honor your ability to maintain your documentation engine, don’t be too ambitious so that it backfires

Sarah Wells: Do you add Who, What, Where When to certain documents to make it easier on those individuals searching through documents? Or make it easier when sharing documents, especially for when newbies come on board. i.e. here are all of our documents but these ones are specific to your job.

• Add a table of contents
• Add 'Here’s all the things related to achieving macro objectives for roles'
• Use categories of documentation for departments, and sub-categories for roles

Thank you to Nicole, Kyle, and HubSpot Academy! See upcoming HUG events here.

Additional resources:

If you'd like help creating your documentation or knowledge management system, I offer courses and templates, as well as a comprehensive guide to documenting your processes.