Techniques for Documenting Your Web Projects
One of the neat aspects of building a number of websites is that, eventually, you’ll often face the same challenge more than once. This means that you’ll know exactly what to do. 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, yes, you’ve written a piece of code that would be a perfect fit? Then, how often was that same snippet almost impossible to find?
Undoubtedly, this is a common refrain 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.
A common practice includes writing a short narrative above each new function, for example, to explain its purpose and relevance to the project. 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 utilized 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
Now, depending on your personality, the mention of the word “journal” may be either dead scary or oddly comforting. And your reaction should probably inform just how you handle this type of task.
In this case, we’re talking about a document that serves as a future 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 done. Open up a word processing document or go all out and create a Wiki on your local install. It can be as fully detailed (or not) as you like. There are no hard and fast rules here.
For example, our design and development techniques tend to evolve over time. 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 its own separate entity. Not sure where to start? Look at what makes this site stand out. Make note of special templates you created, specific code snippets or styles. If you had to do something different with regards to your server, that’s also a great thing to document.
Maintain a Code Snippet Library
Don’t try 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 would be a great solution. It would allow you to categorize things and allow for version control. You can even tie a repository in 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 searching and finding what you need a much smoother process.
An Encyclopedia of Your Work
Web designers love to build portfolios to show off their work – or at least the final results. 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 really can customize it 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.
The post Techniques for Documenting Your Web Projects appeared first on Speckyboy Design Magazine.