As someone who has been building Drupal sites for over 12 years now, I'd like to think that my knowledge and expertise has grown at a rate similar to the power, flexibility, and complexity of the Drupal project itself. For well over 10 years, Drupal training and development has been the focus of my consulting business; over the holidays I took some time to look back and really think about the lessons I've learned and how I can utilize them moving forward.
In addition to documenting the process for myself as well as my current and future clients, I also wanted to share what I've learned with the Drupal community. After all, it is this community that has made it possible for me to have the success that I have found so far. I have worked on projects of all sizes from large Fortune 500 companies to small local businesses. I’ve been alone on project as well as with large teams of developers. There have also been projects with massive budgets as well as projects with no budget. The breadth of this experience has really contributed to my ability to provide more value for my clients.
One word I use often when speaking with current as well as prospective clients is "sustainability". I always want to be involved in a solution that provides good value not only now, but for the lifetime of the project. I want to build sites that are easy to maintain, easy to update, and easy for different developers to cycle in-and-out of. With sustainability, and all of the elements that contribute to it in mind, I present the 11 tips to start a Drupal project right.
1. Commit to a Local->Dev-Stage->Prod developer workflow
Having a professional developer workflow should go without saying, but I often come on-board small, single-developer projects that have a remote development environment and a live environment - and nothing else. At the very least, projects of all sizes should have not only a dev and live environment, but developers should have local environments as well.
There's a lot of focus on DevOps in the Drupal ecosystem (with good reason), but before you jump into a continuous integration/continuous development (CI/CD) system, be sure you have the basics first and then add complexity only as necessary. I've seen way too many projects invest in a full-on CI/CD system only to have it ignored because developers didn't have the time and/or expertise to utilize it properly.
2. Commit to the entire team using a project tracker
This is a bit of a pet-peeve of mine. I'm a firm believe that commitment to a project tracker must include 100% of the development team and stakeholders. Note the "and stakeholders" - this includes project managers, content and QA folks, and anyone else who has a role in the project. How often is a project ready to launch and then at the last minute a stakeholder chimes in requesting changes? This is demoralizing and frustrating for the entire development team.
Project tracker tasks should be focused. Large tasks like "theme the site" aren't very helpful and comment threads in tasks like this often become unwieldy, defeating the purpose of using a project tracker. Train the entire team on using the project tracker and committing to using it for the majority of project task communication.
3. Utilize a remote Git repository
You're not using Git yet? Seriously? Stop reading this and go get yourself and your team trained up (we offer training). Also - commit early and often. Smaller, more focused commits (like project tasks) are easier to manage.
4. Use Composer to manage the code base
This is an article about Drupal 8, so this isn't really optional. While there is work in the community on various Composer-related projects, for now the Composer template for Drupal projects is the de-facto standard for managing your Drupal 8 project's codebase. Don't know how to use Composer? Learn it (we also offer Composer training).
5. Use consistent local development environments for development team
Avoid "it works on my machine" conversations for the rest of your life by ensuring that the entire development team is using identical local environment configurations. Docker-based solutions are tailor-made for this type of thing, but it has been possible for awhile with virtual machine-based solutions as well. A solid local development environment will pay dividends - making it easy to get new developers up-and-running, and allowing developers to focus on building the project, not monkeying around with their local environment.
I've been a fan of DDEV-Local, a Docker-based solution, for awhile - I provide training and I also wrote a book about it!
6. Define information architecture with all stakeholders
This is where I see projects go sideways more often than not. When defining the information architecture (IA) for the site, all stakeholders must be involved. This tip really goes hand-in-hand with the next one, but the bottom line is that this needs to be a discussion. There's nothing worse than getting near the end of a project and showing it to a content author and finding out that there are gaps. Generally, the goal is to get the granularity right when defining IA. This is next to impossible to do without feedback early in the process from all stakeholders.
Review any existing content that is to be migrated to the new system, ask content authors what the issues with their current system are, and be careful not to over-engineer a solution that won't provide enough bang-for-the-buck.
7. Prototype information architecture with content authors
This tip goes hand-in-hand with the previous one - an important part of defining the IA is testing and confirming that everything is accounted for. In my experience, the absolute best way to do this is by prototyping the system. Allow your actual content authors, editors, and admins to test-drive the new architecture by adding and editing content on a prototype of the site. This needs to be done very early in the development process, so the focus should be 100% on the add/edit forms - not the output. In fact, I recommend not putting any effort into theming the output at this point, making it crystal clear that the prototyping exercise is to confirm that the set of entities, bundles, and fields designs are on-target.
I really cannot stress enough how important this step is. IA mistakes made early that are not corrected will be a burden until they are corrected (if ever). It's normally relatively easy (and inexpensive) to fix IA mistakes early - quite the opposite if they are left to fester and other parts of the site are built upon them. I have never been part of a project where the IA prototyping didn't result in important updates to the IA.
8. Create a style guide
If you're building a custom theme, then you probably need a style guide. Part of a solid UX/UI design is consistency in design. Consistency brings user comfort. When users are more comfortable on your site, they'll spend more time there.
Style guides can be as simple or as complex as they need to be. At the absolute minimum, I would recommend that a style guide contain basic typography and a color palette. You'll need to consider how/if typography will change based on responsive mode (are H1s the same pixel size on mobile as they are on a desktop display?) Similarly, you'll want to think about how the header/navigation/footer respond to various screen widths as well. Have an element that appears throughout your site? Then define rules how it looks in various places and various screen widths.
9. Create wireframes and mockups as necessary
Similarly, if your project is going to have a custom theme, then you're going to need to design the layout of key pages. How are landing pages arranged? How do they respond at various screen widths? Think about the entire site and design wireframes for a representative sample of pages. Only 2 or 3 wireframes are necessary for many projects (home page, content page, interior landing page).
Consider these representative pages as a group, not individually. Look for common elements (easier to theme) and value consistency. If every page is a one-off, then implementation costs will rise.
Start with wireframes and generate only the mockups you need. Often, between a solid style guide and some good wireframes, mockups aren't necessary in many cases. Think of the style guide as a box of LEGO bricks that can be assembled into mockups in various configurations. If time and budget is limited, favor the style guide over mockups.
10. Use the Configuration System
Drupal 8's configuration system provides a powerful tool to easily push non-code configuration changes between environments. The "trick" to using it is that the entire team has to understand and participate in the process. If the development team is five people, and only two are using the configuration system, you're going to have rough sledding.
The configuration system will help enforce a solid developer workflow, encouraging team members to update and test configuration (like a new View) locally before pushing it to remote development environments. A byproduct of using the configuration system is that config changes can easily tracked by the project tracker via commit messages.
11. Define realistic and meaningful milestones
There's not much that kills developer morale and confidence in a project more than lack of project leadership. At the core of this is often a lack of project planning and milestones. All team members should be involved in the setting of goals and milestones for the project. A single milestone of "the site must be done in 5 months" doesn't cut it. The entire team should work together to define realistic and meaningful milestones. Take into account non-project responsibilities of team members, identify and plan for potential pain points in the project.
Project leaders need to listen to team members and provide training and professional guidance when necessary. Most developers are problem solvers who like to learn new things. Project leaders should embrace and leverage this for the betterment of their projects, the result will be a positive one for the entire team!
Mike Anello is the architect and instructor for DrupalEasy’s Drupal Career Online, which includes intensive live online sessions, rich learning resources, an active learning community and hands-on projects designed to provide those who need to get skilled up in Drupal with the best possible start. The next session of the DCO starts February 25th. If you’d like to learn more, you can sign up for a no-cost Taste of Drupal mini-webinar.