Techniques for Documenting Your Web Projects

One of the neat aspects of building websites is that, eventually, you’ll face the same challenge more than once. This means that you’ll know exactly what to do the next time around. That is if you remember where and when you’d seen the issue before.

How many times have you needed to accomplish something and realized that you’ve written a piece of code that would be a perfect fit? Then, how often was that same snippet almost impossible to find?

This is a common challenge for web designers. That’s why writing some basic project documentation can prove to be beneficial. By putting such a system in place, you’ll have an easy way to go and find that time-saving snippet.

Whether you’re working on a new project or looking through some past ones, here are some tips for documenting what you’ve done.

Comment Your Code

This one seems a bit obvious, but it’s no less important. As we write code, it makes sense to add appropriate comments about exactly what it does.

Common practice includes writing a short narrative above each new function to explain its purpose and relevance. Beyond that, adding notes at other key places within those functions allow us (and others reviewing our code) to gain a better understanding of how everything is put together.

And this practice isn’t just for complex languages like PHP or JavaScript. It’s also perfect for CSS. Pointing out specific styles and where they are being used is great for finding exactly what you need.

It often feels like half of the battle is just remembering why each line is there and what it’s supposed to do. Commenting can take a lot of that ambiguity away.

Create a Journal for Each Project

Depending on your personality, the mention of the word “journal” may be either incredibly scary or oddly comforting. Either way, there’s great value in the practice.

In this case, we’re talking about a document that serves as a future project resource. Should the website break or require a new feature, this would be a place that you can reference for details on how things were configured.

Open up a word processing document or go all out and create a Wiki on your local install. It can be as detailed (or not) as you like. There are no hard and fast rules here.

For example, our design and development techniques tend to evolve. The approach you took a few years ago may not resemble what you’re doing today. Thus, it’s important to put various elements of the process into writing.

Plus, even when using common systems and libraries, each website is a separate entity. Not sure where to start? Look at what makes the site different from others.

Make note of special templates you created, specific code snippets, or styles. If you set up a unique server configuration, that’s also a great thing to document.

Maintain a Code Snippet Library

There’s no need to reinvent the wheel when it comes to code. Much of what we write is infinitely reusable. Even if it doesn’t fully fit in with the needs of your new project, the right snippet can serve as a solid starting point for further customization.

Organizing disparate bits of code, however, can be a challenge. You could just copy and paste useful pieces into a document and retrieve them as needed. But for those who write a lot of code, this might get out of hand rather quickly.

A GitHub repository could be a reasonable solution. It would allow you to categorize things and establish version control. You can even sync a repository with another service so that you can use or access it in different ways.

Regardless of how you put a snippet library together, you’ll want to develop some sort of system for tagging, categorizing, or otherwise labeling each snippet. For instance, you might want to add things like the coding language used, purpose, relevant application (such as WordPress), or library (React, Vue, Bootstrap). This will make finding what you need a much smoother process.

An Encyclopedia of Your Work

Web designers love to build portfolios to show off their work. But keeping track of projects internally is also a worthwhile endeavor. It can help you troubleshoot and build upon existing websites while providing solutions for new ones as well.

You can use any or all of the above techniques to get things organized. The best part is that you can customize things the way you see fit. Whether that’s through voracious notetaking or simple reminders, it will help you better understand the what, where, when, and why of your web projects.