Skip to main content

Check out the "Drupal at your fingertips" developer reference guide

Published on

Selwyn Polit has created a fantastic Drupal 9 and 10 developer reference guide called Drupal at your fingertips. The book is a reference guide that explains the various APIs within Drupal and examples of code for using them. The book's contents are available online, and all of the content is licensed under Creative Commons Attribution 4.0, making it available to share and modify with attribution. You can find the Drupal at your fingertips book online at: https://selwynpolit.github.io/d9book/ and its source at https://github.com/selwynpolit/d9book/tree/gh-pages.

I asked Selwyn a few questions over email about the book.

Matt: What inspired you to start the "Drupal at your fingertips" reference guide? Did you have a collection of favorite blog posts and snippets you had collected along the way and wanted to compile into a resource for others?

Selwyn: Exactly.  I have always tried to find an ideal way to store my notes for things I want to reuse (or tuck away for use later).  Some variations include NVAlt and Notion, markdown files, and tons of bookmarked links. After many different efforts, I finally just settled on using good old MS Word.  So that resulted in a monster document called "Tips - Drupal 8" with all sorts of code snippets.  This beast is now 588 pages and over 92,000 words.  It has a table of contents so it is kinda possible to find things, but it isn't well organized. 

I'm really inspired by open source and Drupal especially, and have often wondered what the best way was for me to contribute more to the project. As I kept trying to reorganize this info in the word document, it occurred to me that a book might be a useful solution, so I started Drupal at your Fingertips. 

I wanted this to be a Drupal project, but as I explored the options, it looked like Markdown and Github Pages was a really good solution. It is quite easy to get started, has the benefit of the Github infrastructure behind it, is the right price (free!), and should work well for community involvement. 

Finally, much of the work we web developers do is ephemeral.  So many of the sites I spent hundreds of hours working on are no longer using that code that I wrote.  I want to make something that was a little more enduring, so maybe this is it.

Incidentally, the useful lists of Blog Posts and code snippets that are my favorites are all linked in the reference section at the end of each chapter and there is also an entire chapter Learning and keeping up with the latest on Drupal which links to lots of really good resources.

Matt: The project's repository has a Drupal code base alongside the book content; what is it for?

TL;DR A Drupal site that includes much of the code from the book where I confirmed that the samples worked.

Some of my notes from the original document included code or links to articles with code that I hadn't really tried, so I wanted to make sure most of my examples actually worked.  This project is that effort.

As I was creating the chapters, it dawned on me that it would be useful to make that code available with the book, so I started creating modules where I tried out the code samples. You'll see custom modules like date_examples, hook_examples, and di_examples which correspond to their respective chapters in the book.

The Drupal codebase (in the main branch) is a functioning Drupal 9 site called D9book installed with DDEV and includes a database dump and config export.  It has some Devel-generated content where needed to test things.  Users should be able to clone that repo, load the database (using ddev import-db) and experiment with the code examples further. 

Matt: How does someone contribute to the reference guide? 

Community members are invited to contribute by making edits and pull requests at this link on GitHub. There is a very simple online editor which automatically forks the repo and lets you type your changes directly in your browser in markdown format. It is quite friendly and painless.  You don't have to go through the steps of forking the repo.  You can just click login to Github, click the pencil, and go.  Even creating the Pull request is quite straightforward.  Several members of the Drupal community have contributed already, which is very satisfying.

I will look into adding an edit link on pages as well as a CONTRIBUTING.MD page.

There is also a Giscus Widget at the bottom of each chapter where people can add comments and reactions.  These are stored in Github Discussions and require a Github login, but that is a pretty low-friction way for folks to comment.  I always love the User Contributed Notes on https://www.php.net where some of the best explanations often appear.

Matt: Any plans for a distributable copy for offline usage?

I'm starting to explore creating a version of the book at Leanpub.com. If all goes well, that should be available in the near future.  That would allow people to contribute financially and download a nicely formatted PDF version.

I'm available for one-on-one consulting calls – click here to book a meeting with me 🗓️

#