Last year I had the chance to collaborate with a Drupal company in Greece for a large scale Drupal 8.x project. One of these that you say Drupal was made for!

It was early 2016 when Drupal 8.x had just arrives. At that time thing were a bit confusing (although promising) with the new Drupal version. Composer adoption was still in "alpha", popular Drupal contributed modules where not ready for production, new concepts in core had to be learned, Phpstorm (or another advanced IDE at least) was required etc. In general things were unclear and the development team needed a guide in order to avoid the "search on Google" disease.

One of my responsibilities for this project was to document the "best practices" and HowTo​ work with the new Drupal version, with software such as git, Docker, composer and all the software needed. In plain English I had to create, maintenance and update the official documentation of the project.

After some discussion we had internally we decided to publish these docs using the ReadTheDocs.org platform under an open source license (Open Publication License). We did this not only to make the things easier for us or reuse the knowledge we got but also to get help from anyone else that wanted to do the same. The audience are people that already know Drupal 7.x and want to dive into Drupal 8.x. In fact, I was also learning new concepts and methodologies (but, yes, with Drupal we never stop learning new things, don't you agree?)

Copying the first lines of the docs to get the purpose of the docs:

A useful manual for Drupal developers, themers and site builders that want to start collaboration work with the new Drupal 8.x stuff.

The initial documentation created to help us in the maintenance and development of a complex Drupal 8.x distribution but became more generic and public available in the future.

Common best practices are in place and new methodologies of development are proposed on this manual.

Before starting I 'd like to describe a bit the project I am talking about.

It was a multilingual portal with multidomains, unified Dashboard per (sub)domain, content workflows and many content types and fields. More about the parameters can be found at dropdog.readthedocs.io/parameters. We decided to use Features module and Drush make files, Github and the Git Flow model for the git branches. We were also using Docker for local development environments as also as other Shell scripts to automate the processes.

The Docs are separated into 11 major sections which are:

  1. Learn
  2. Parameters
  3. Infrastructure
  4. Development
  5. Theming
  6. Tests
  7. Reviews - Entity
  8. Reviews - Views
  9. Scripts
  10. Development thoughts
  11. Terminology

 

The titles of each section are self describing. Unfortunately some sections are incomplete and contain only the headers  (Scripts, Tests and Terminology).

One interesting thing I would like to promote here are the naming conventions we decided to use while developing the website (entities & fields, views, features etc).  Using the pattern field_CONTENTTYPE_SHORTNAME and other similar conventions, for example, allowed us to make changes in bulk, search for issues more easy, avoid Features issues and conflicts with configuration and "standardize" the theming. Furthermore, in order to make some human reviews for Entities and Views we created lists of checkboxes ready to be copied on a Github issue when a new Entity or Views is created.

Another one is the rules we had when setting User Roles such as that "Every custom module should define its own permissions. Never reuse an existing permission!" I still believe strongly that this rule should be implemented with Drupal core modules also but this is another issue that will not discuss now...

For the Theming we followed a variation of the Atomic Design approach (see Patternlab) and created our own "Drupal specific" folder structure expecially for the scss files. Of course for scss we set up some well known rules and linting to avoid development conflicts. Another useful thing here is that we followed the desktop first design. That means that we first designed for desktop but with mobile in mind and not the opposite since the mobile visits were a few (and there were no obvious signs that this would change in the future).

I could say a lot for the whole experience but it's better to let you "explore" the docs and take what you find may be useful. Pull requests and suggestions are always welcome.

dropdog.readthedocs.io