How to Write & Update Wikis Well
First, read
A Culture of Documentation! This explains the high level info on why documentation is great for us and how we can decide what should and shouldn't be documented.
This wiki here, however, is the nuts and bolts, the nitty-gritty of how to communicate how to complete a task or process.
First and most importantly, here is our standard on what makes a wiki good:
Imagine you're about to send the wiki you are writing or updating to your friend or a family member, one who has never worked in real estate. If you write the wiki and think your friend or family member could most likely complete the task with no more guidance than what is in the wiki, then that is a successful wiki!
We're often bringing on new team members who don't know how we work as a company, and often who have no experience in residential real estate. Make the assumption that at some point, this wiki will end up going to someone who has never been exposed to anything in the company. This will mean linking to login information pages they may need, linking to any other related wiki or wiki process, assuming they don't know what a 'T-47' is and linking to our
Acronyms & Terminology page often.
We do offer more guidance via Hangouts, consistent feedback over email, screenshares, phone calls, texts, but we still want wikis to serve as a standalone place where a person can always refer back to for anything they need for any piece of information related to a process.
High Level Notes & Some Scientifically Proven Methods! (We love science.)
Explain everything first.
Our minds are primed to be especially good at remembering the first thing in a list. So, we want to explain, in a 1-3 sentence summary at the top of every wiki or process, the following things:
- Why we need to do this.
- The core of what's being done here.
- How we'll go about completing it.
For example on setting up ShowingSuite:
"We need to set up ShowingSuite, a service that provides seller with showing notifications and feedback from agents. We do this so that sellers are looped in on showing activity and automatically receive feedback that agents provide after showings. We're going to upload seller information and property information into the ShowingSuite system and link it to the listing's Supra lockbox and the MLS listing."
Before writing a wiki, check if one already exists
First, check Tettra, we may already have something for this! If we do, but the wiki looks outdated or just needs some work, you can simply update that one.
Second, if no wiki exists, see if there's something on a service's help page/knowledge base, or something out on the internet in general. For instance, we don't write wikis for Appfolio or DocuSign, because both of these services already have really great tutorials. So instead of writing a new wiki, we can just refer to these pages.
If there's a more general task like 'resize a JPG to under 1MB', for instance, there are plenty of resources already online for this which we can rely on instead. Whenever it makes sense, please feel free to link to these resources on related wikis!
Make Everything Readable
Pretty straightforward! We want to make sure it's easy for others to read. Please always have someone else check a wiki you're working on to confirm it's readable. Ask them to read it as if they were brand new to the company.
Easy hacks for this: use the built in features in Tettra to improve & vary formatting, please make use of lines to break up sections, number or bullet lists, embed photos & videos!
Make things more efficient as you write by explaining the process to a rubber duck!
This sounds funny, and it is, but it's a time-tested technique used in software development. (Obviously we are writing our process for intelligent human beings, and not coding a computer program, but hear me out).
When developers are trying to fix a bug, or just clean up their code, often they will explain what their code does and why as if they were explaining everything to a rubber duck. As they do this, they have to critically analyze what the purpose of each process in their application does, and explain it in plain terms.
While you're explaining to your rubber duck, you may find something doesn't make much sense. That's good! The next step is to find out why it doesn't make sense and fix the way we do things so that you can explain it to our duck friends. If you think something could be done better, please let me (Alex) know your thoughts on what's wrong, how you think it could be done better, and we can coordinate on it!
More pictures = better wikis.
Research backs up that pictures improve understanding and retention. Please use as many as possible when possible!
If you need to write up a quick bullet list with no pictures just to get info down quickly, then that's fine, but please create a task to go back and add in more pictures later! Use the screen capture applications Jing or Snagit by Techsmith to easily take pictures and videos:
https://www.techsmith.com
Explanation Structure
- Whenever it makes sense, please explain processes sequentially (i.e. move step by step as you go down the wiki), and please use bullet points.
- If a step needs more explanation or has some critical information that needs to be communicated, please add another line and 'tab over' to create a bullet point as done here.
- Then, move to the next step.
- Let people know when they're done with the process with a 'Then you're done!'
Explain Contingencies
If there are multiple actions or possible steps that can be taken, then use "If-then" statements to denote this!
For example
- Next, we need to find out if we need a survey.
- If the property is a condo, then a survey is not needed.
- If this is an estate sale, then a survey is not needed.
- If the property is a single family home, then a survey is needed.
Message Templates
Use message templates to make messages clear! You can use these with 'Tables'.
After you've created a table, you can add or remove rows & columns to meet the message format you need.
On message templates, we want to include 3 things: a title, who it needs to go to (recipients), and the message of the body.
- Recipients refers to who needs to receive the email.
- Title is the subject of the email.
- The last section is the body of the email.
|
Recipients: Client, CC BA.
|
Title: Congratulations on your Home!
|
{{CLIENT NAME}},
Congratulations on the contract for your new home at {{PROPERTY ADDRESS}}! We're very excited to work with you on this, and I'll be sending some more info on the next steps shortly.
Please let us know if you have any questions, thanks so much!
{{SIGNATURE}}
|
When you see any field in {{BRACKETS}} like this, it means that this is a field in a template that needs to be edited, and you'll edit it with the information requested in the brackets. Please use these fields whenever there is a variable we need to input, and describe the variable inside of the brackets (as seen above).
For instance, if I wanted whoever is going to complete this message template to send this to our client Jim who just executed a contract for 5607 Kernel St, they would send this:
Jim,
Congratulations on the contract for your new home at 5607 Kernel St! We're very excited to work with you on this, and I'll be sending some more info on the next steps shortly.
Please let us know if you have any questions, thanks so much!
~Alexander
|
Mark Down Important Information using "Failsafes"
A failsafe is a note to watch for to help avoid easy & common errors. These are instances where we need to communicate a critical piece of information about a process to help avoid errors when completing a process. Please use these wherever makes sense! If we make a mistake in a process that was an easy mistake to make that had high impact, we always want to go back & add something in.
To make a failsafe like the one below, click on a new line and use the 'Callout' button on Tettra as seen below, then enter your critical text!
Important: Don't forget your rubber duck!!
Record Videos For Quicker Results (and then make a written wiki later)
If you need to show someone how to do something, but you're short on time, videos are great for this!
Use the screen capture applications Jing or Snagit by Techsmith to easily take pictures and videos:
https://www.techsmith.com.
CloudApp is also great!
The key thing here is to always make a task for yourself (on Asana for instance) to go back and write up a wiki for this later.
Here's a good example!
Update Constantly!!!
We are always improving wikis. Whenever you notice something that might not be on the wiki, or we have changed a process, please always check back and update it!
Finally, ask your team-mates to audit and send you notes!
Often, things that may seem obvious won't seem so obvious to someone else and they'd want to see more information.
When you're done writing or updating your wiki, please always send the wiki to 1-2 team members (including Alex) and ask them to send at least 1 note (preferably more) based on the info in this wiki (please link to this page).
If no one sends you any feedback, please follow up with them until you do get at least 1 note of feedback from someone. Make a task to ensure that, for every wiki you write and process, your update is reviewed.
You will never get in trouble or be shamed if something doesn't look right or needs improvement; we're all doing this all of the time, and even Eric's wikis are reviewed & updated by other team members.
