Where do you store your onboarding documentation?

With the myriad of tools, tips and tricks that can exist in a team, onboarding can be a fun challenge :grin:

I used to store our onboarding documentation on our gitbook repository along with the user guides for our application. Before that, they were stored in just my brain though :see_no_evil:

Where do you store your onboarding documentation?

3 Likes

I’m onboarding at the moment…there is so much stuff to trawl through…whether it’s in some central repository, training sites, HR resources, Benefits and so on. It’s a bit of a minefield, knowing where to get the right information.

3 Likes

Confluence and/or Google drive or similar. I prefer confluence over G drive. I have also seen some nice examples of documentation on Notion https://www.notion.so, but I don’t know how good it is for a company.

My criteria for selecting a source:

1 - Has plenty of tools/options for formatting and visualization.
2 - Excellent search capabilities.
3 - Can give structure to documents like table of contents, footnotes, attachments etc.
4 - Can easily allow me to organize documents.
5 - Is pretty to read.
6 - Supports code formatting.
7 - Allows users to give feedback easily easily & stores them neatly.
8 - Tracks changes like version control & can notify people when something is changed.
9 - Can play content (e.g videos, pdf etc.) without having to download and play.

2 Likes

I’ve got stuff all over the place! :joy: Only partly joking. Our test coommunity has a “test handbook” built with MKDocs which contains lots of stuff. Onboarding info, links to other useful places, docs, process stuff, guides etc. It needs to be tidied, but its meant to be “the place” for test info.

2 Likes

We used to have a tonne of documentation stored in our Azure DevOps wiki. It was a good way to store things because it was searchable and always accessible.
Then we realised that it was rarely and poorly maintained and no one was really using it.
Recently I started to use mind maps for tips, useful heuristics, team composition and test environment set up that we store on our document management system. I don’t think we document anything else…

We give any new starts a tour of the application we are currently testing and task them with learning it.
We give them a charter and ask them to spend a fixed amount of time surveying the app with the purpose of learning and to raise any bugs they encounter.
A follow-up task is to create a product coverage outline (a list of all testable elements that they can identify). This is essentially a formal model of what they think the application is and what it does.
After each task we also ask for a session report to encourage note taking and to get them familiar with high accountability exploratory testing.
We debrief them and use these meetings for coaching.

4 Likes

These are amazing suggestions! Thanks.

Do you have any advice on how grandular to get with the product coverage outline?

4 Likes

I’m not sure if everyone is still doing this, but for the last while we had new starters do a product familiarization exercise, but built as a challenge with 2 parts or goals.

  1. install the product and get it to connect and working. Your office email address is your free product license key, activate it. What technical aspects of the setup would you like to understand more about?
  2. Write down notes about your subjective experience of setting up an account and getting things working. describe how your expectations or ideas of what should happen were either disappointed, or were met.

So alongside all the boring onboarding stuff, the new starter gets a day to explore the “customer experience” as a “newbie”, and can give us product feedback which we cannot get from our own selves.

3 Likes

Great question and suggestions indeed. A shared knowledge management system, in my case Confluence.

I’m currently working on our Onboarding process and a few key things during the process we discovered was the wealth of information we needed to capture but yet still not overwhelm the new team member. While writing I was asking myself:

  • What would be the key thing this person should receive after each area of the document?
  • Does it create more confusion for them? Or does it increase the gap in getting them fully operational?

Some more specific things we were keen on including were Use Cases for customers, Feature Matrix, tools that we use, and also WoW, DoR, DoD so that they understand the culture of the team and see themselves as a teammate. We definitely agreed that it certainly isn’t perfect and requires finetuning as new hires use it. That’s my 2 cents.

2 Likes

we use a lot of concepts and ideas from things like TechDocs Documentation · Backstage Software Catalog and Developer Platform where we try to have all of our documentation for apis along with onboarding within repos (which ends up getting rendered to single teams site, we do this via use of sphinx which can render markdown files, etc to create static site)

for onboarding new members, we have taken high level strategy:

  1. we have specific modules that members have written that have things like (a) knowing how to use and write tickets in JIRA (b) basics of python, using jupyter notebooks, and more. namely reusable modules we can use across team
  2. we will then have section on boarding that someone new would be assigned, that has a specific track outlined (these tracks will be different depending on the roles eg dev, qa, ba, etc). this will be mixture of items to review, tasks to complete, etc. usually assigned an onboarding mentor (which can change depending on portions of onboarding, but namely someone that may point person and someone that will help with review/completion of tasks).
  3. have a specific onboarding repo, we have this as it is more a sandbox repo, as portions of tasks is understanding the integration of JIRA, git, PRs, etc. this repo will be used for place to do certain tasks and small scale projects. it allows for a “learn by doing” style

overall above tries to allow for (a) re-usable documentation (b) allows for documentation to have proper and easy review (when people make additions) (c) ability to have predefined tracks/tasks that we can just send new hires/members thus lessoning the burden on managers and such to have to onboard, can just plugin when needed (d) allows for the whole team participate and grow the documentation. (e) allows onboarding to be done in a more “learn by doing” manner, each team member is going to be different on what they pick up fast and what they may need more work on allowing for these types of tasks that will have review in PRs and such allow for onboarding mentor easy ways to plugin and provide feedback so member can start on right track)

2 Likes

Brilliant. I contracted at a place briefly that used a web app that let you create “learning tracks”. Basically bullet point learning curriculums. This was a great trick because you could choose a “track” from it, without your manager getting involved and challenge yourself, knowing that the challenge set was not only just the right level for you, but also meaningful to your learning in the company. And that you could then go to anyone at work and say, "can you help me with this learning task X "? I’m at this point in this task, and know that the terminology you used is correct.

1 Like