How to organize your docs for the first time… or again

Finding yourself wistfully wishing your knowledge was better organized? Or wondering where to fill in missing crucial documentation? If you’re new to tech writing or inheriting a hot mess of knowledge, cleaning up your docs isn’t as hard as you think with this 6-step process to get you started.

My parents’ cluttered basement with documents over 30+ years old.

Organizing knowledge can be a lot like sheep herding cats — just downright difficult. Though this is something that most tech writers/documentarians deal with regularly, you don’t need to be one to clean up your documentation and keep it all in one place.

Not sure if you need to organize? Ask yourself whether your knowledge is scattered everywhere and hard to keep track of. Or maybe you and your team are running into situations like these:

• Veteran employees leaving along with their acquired knowledge
• Subject matter experts becoming sick or going on vacation
• People duplicating the same knowledge, not realizing another had already made it
• Onboarding new hires is slow, their learning curve nearly overwhelming

Or perhaps, you’ve stumbled across some undernets, an apt term coined by Jacob Touchette (source):

Undernets are the “non-formal and unintentionally walled off bits of knowledge that [folx] document in private”, also known as “rogue docs or sheets [others] create for themselves. These are often incorrect, out of date, or not shared with the entire team.”

Undernets are very real, and they can be a symptom of a larger problem: people don’t trust the knowledge they’ve been given, or can’t access that knowledge easily, so they turn to creating undernets of their own.

Ready to start organizing your knowledge? Here’s my how-to-guide, broken down below:

1. Collect the information and store it in one place

This is where you have to search far and wide to collect them all (like Pokémon). So round up all your coworkers on your team, and have them share their files and documents with you. Look extra carefully for those coworkers who hoard information like dragons hoarding treasure, so you can get rid of all undernets in one fell swoop.

When you collect information, store them in a central temporary place, or in the final home of where you’d like the documentation to live. Whether that’s your company’s Confluence wiki, Google Drive or Dropbox… you can copy and paste everything you collect in there, or upload files as you get them. Keeping everything in one location makes it easy to track what you have, and more importantly, what you don’t have.

2. Create a catalogue

Once you’ve shepherded all this information into one place, it’s time to catalogue what information is available to you and your team. The best way to do this is to create something resembling a Table of Contents:

An example of what your catalogue might look like. I prefer to use a whiteboard for this, or you can use any text editor app.

Organize content by a particular category or theme, and you can even add sub-categories or nested lists underneath each as you catalogue every single item in your central repository.

3. Determine what’s missing

Now that you have your existing knowledge catalogued, this is where you start filling in the gaps with what’s absent or lacking. When you do this, distinguish the missing content you add in a different colour, or highlight the text, to indicate “needs more info”. You’ll flesh out the actual missing content in a later step.

Don’t be afraid to tap into your audience — your coworkers and stakeholders and anyone else who relies on this information will certainly have lots to share on what they’d like to see added and documented. As a bonus, if you use email regularly or chat apps like Slack, check your inbox and Slack channels for repetitive questions that often come up — use those questions as inspiration for content that can be created!

4. Test and build the information architecture

Information Architecture (IA), in case you’re not familiar with it, focuses on organization, structuring and labelling content in an effective and sustainable way. This helps readers find information and complete tasks — like finding your documentation!

Look at your catalogue from an IA perspective — does the way you’ve organized content makes sense and is easily findable? Or is there room for improvement in where the information is ranked?

If you’d like to user test your IA and see if it’s effective, I recommend doing a Card Sorting exercise, which is a common UX Testing Tool (Google has a great book on it here). Put some of your coworkers through this exercise with your catalogue, and see if they rearrange it into an order that’s identical to yours or you may find yourself being surprised.

Results from the second IA user test session on reframing our internal knowledge base. I like using sticky notes and markers on a whiteboard for this activity because you get have more flexibility with moving stickies around and you can even draw relationships between them as needed.

Running through one or more card sorting exercises will help inform the final IA design of your catalogue from the feedback and analysis received.

5. Tidy up your content

This is the fun part — the meat and potatoes of the process. If you’ve been storing the content in a temporary place, you can start moving it into its new final home. If your content is already where you want it to live, then you can start by reorganizing the structure according to the new IA/Table of Contents you’ve put together in step 4 above.

Then you’ll want to ensure a copy of your IA/Table of Contents lives as the landing page of this central place, or is readily available in this central place. All visitors can reference your Table of Contents as another wayfinding tool for looking up information (or to see what’s available). By the end, your content should look consistently formatted, and be structured in the hierarchy you’ve crafted.

6. Share the news and update regularly

Now that all this knowledge is centralized in one place, share it with your coworkers, stakeholders (like your Product Managers) and anyone who requires access to it! This will help prevent any new undernets from forming and increase the value of your knowledge.

To ensure your investment in this does not go wasted, make sure this central repository of knowledge stays updated. Whether that means folx take turns cleaning and updating the documentation, or a sole person takes it on — add new information as it gets created, groom all your existing content, and don’t be afraid to delete it if it’s no longer useful.

From start to finish

If you’ve followed this process, you’ll now have one source of truth for your documentation and one central place to direct people to. Knowledge is only treasured if it continues to be valuable to others, so maintenance is key to its success and to your return on this investment of your time and efforts.

And hopefully your new centre of documentation is something that you and others can be proud of (or in the words of Marie Kondo, it brings you all joy!).

Do you have a triaging method that works best for you? Feel free to share your process here, so we can all learn from each other’s documentation experiences!