Document to survive

We owe it all to documentation

Since the dawn of humanity, our ability to thrive is a result of documenting our experiences and sharing them with future generations. We have an innate, and often subconscious, urge to help others make the most of life through instructions informed by our own experiences.

From the earliest cavemen carving hunting tactics into the walls of their land, to Doctors recording their observations in medicine, every artifact of knowledge over thousands of years has had a compounding effect on who we are today. Where would we be if Darwin or the Apostle Paul hadn’t recorded their experiences, or if Edison and Tesla hadn’t shared their experiments with the world?

As designer and developers of the World Wide Web, we are participating in the most impactful medium humanity has ever created to make knowledge of our shared experiences accessible. Most of what we create is for the consumption of others (this article included!), but we must not stop there. We have the opportunity to document HOW we create for the web, so those that come after us can do the same and more. This can be a catalyst for making knowledge exponentially more accessible to everyone.

Teach others to fish

Give someone a fish and they will eat for a day, teach them to fish and they will eat for a lifetime. Build someone a website and they can sell for a year, teach them to build (or edit) a website and they can sell for a lifetime.

Whether you are a freelancer building sites with clients, or collaborating with fellow creatives on a team, the goal is to set others up for success. One of the tools I have found very effective in doing this is documentation. Like the cavemen before us, documentation is simply a means to record what it was you created, how you created it and how others can interact with and build upon it in the future.

For you, it will cost you an initial investment of a few hours, but yield weeks of time savings in the future. It can be a reference for your future self to remember how you did something, as well as teach others in the future after you have moved onto other projects and teams. For a client or team member, it is a service that differentiates you from the crowd. It is a symbol of quality and expertise in your work. It is a complimentary insurance plan that instills confidence in the longevity of value you have created.

A doc you meant to be helpful

So how do you create documentation in a way that isn’t just noise into the void, and time you could have spent elsewhere? As with all things, my best experience has been to start simple, but with at least some research that plans for the best outcomes of scale in the future.

Choose a doc tool

The future is now when when it comes to products you can use to make documentation creation efficient, intuitive and even accessible across all of your devices.

My personal doc tool of choice has been Notion for the past couple of years due to its balance of simplicity, use cases, and markdown writing experience. It is also the tool we use everyday at Shapemaker to not only write notes and documentation, but even track tasks, ideas, timelines, and resources that are the backbone of the studio.

On larger teams, like my role at Webflow, I have also enjoyed using other modern tools like Coda, Google Docs, and Atlassian's Confluence to write and share content with others on my direct team and beyond.

Whatever you choose, ensure it is a tool that allows you to organize your files, and ideally search and filter for them as your library of knowledge scales over time. To narrow the options, first try making a quick list of what matters to you, and your team if applicable, for writing experience and file accessibility, then sign up for a few options that are most interesting to see which fits best in practice.

Organize and outline

One very important aspect to successful documentation is discovery. If you, your team or a client struggles to find what they are looking for it will be the first friction point that prevents your documentation from being useful.

Once you have organized documents into folders, tables, tags, etc. try creating a quick template for how you can start and structure each document. This can be very simple to start, with a heading, overview, authoring details and common section titles most documents may use.

Tip: If you do end up using Notion, you can store all of your documents in a single database (table, gallery, list, etc) with categories, tags and attributes of your choosing, as well as create your own template to start from each time you create a new document.

Write and record

Creating each new document is often best approached in bite size chunks. I often first write in each section headline to understand the highest level of content I want to document. Within each section, I then format in sub headings and/or bullet points on the main points to make, as well as note any opportunities to drop in rich content like images, screenshots, recordings or linked resources.

The goal when creating the final content is to provide as much context and instruction in as few words as possible. The documents I have found least successful (useful for others) were those that I got too heavy handed with explaining every detail that lead to novel length notes.

Often times a simple introduction to why and what a section is about, followed by bullet point style outlines of how to understand, edit and add upon the topic is ideal. As you need to provide more direct, in-depth instruction, consider using other modern tools like Loom to record yourself walking through a process in real-time. If a more static medium that video is preferred, but you still want the efficiency of recording yourself, check out tools like XXXX that will automatically create notes and screenshots of your actions while performing a process.

Share and revisit

Your documentation is only has valuable as it is available. Once after completing the first version of your doc, consider all of the places you can share and reference it for maximum awareness and availability. Below are a few places that may make sense depending on your situation:

• Announce it in a shared communication tool like Slack or email.
• Bring it up in a call with your team or client, and allow for a few minutes to go over it at a high level,
• Link to it from a style guide or hidden instruction page within the site/project the documentation is for.
• Add it to a resource list in your project management tool, client dashboard, and/or team wiki.
• If the content is generalized, and ok to share with the public, consider sharing it on your social channels and within a case study of your portfolio.

After getting there word out about your shiny new doc, take a moment to consider when a good time may be to revisit the doc in the future. This may be after the launch of another major phase of the project, or a time oriented check in like one year later. Be action oriented about this by creating a future task, agenda item or even a calendar reminder.

Empower the next person

Come your next project, consider adding a task and some intentional time to document your efforts for the next person, whether that be a client, team member or your future self. Do it consistently, and several projects later it will become as obvious and natural as the main deliverable itself.