Drupal 8 Theming: From Code to Documentation

Last week I took a step back in time and walked you through the trends we've seen in Drupal theming over the last few years. Let's now take a look at where we are today. There are two places I tend to look for information when I'm researching new topics online: my network of friends and colleagues, and project documentation.

I love attending Drupal events because it gives me a chance to learn from my friends and colleagues directly. Even if I don't have a chance to attend an event, DrupalCons are recorded (and increasingly so, camps are too). So if I want to find the latest information about a topic, it's a simple matter of attending a presentation or listening to the recording.

One of the most accessible theming presentations I've seen was delivered at DrupalCon Sydney. Sadly I didn't get to see it in person, but the slides for presentation are available at jenlampton.com (and the video on YouTube). (If you've seen other great Drupal 8 + Twig presentations, please post the URLs into the comments below so others can find them!) In this particular presentation, we learn the guiding principles behind the Twig project and some technical implementation details, which are useful for comparing theming in Drupal 7 and Drupal 8.

[Edit: updated the URL for the video.]

The guiding principles are worth repeating here:

• Start with nothing. Core default markup should be semantically simple with few HTML elements, and added only as needed.
• Build from use cases. Don't assume you know what people want. Don't add features based on "What-if?" Think about the 90% of use cases.
• Provide tools. Give front-end experts a way to achieve specific goals; goals that apply to the remaining 10% of use cases. Keep in mind that complex problems may require complex solutions.
• Consolidate. "Your markup is not special." Don't make something new. Work toward common theme functions that modules leverage (i.e., a Theme Component Library).
• Visibility. You should be able to see what's going on in a template without reading docs. Twig provides a lot of this by virtue of its syntax (i.e., it looks like HTML). Form follows function.
• Consistency. Do the same things everywhere; follow patterns. Use similar variable names across templates if they represent similar things.
• Don't dumb it down. Complexity should be reduced, but not obscured. Themers can understand template logic and loops. When complexity exists, use comments for explanation.
• Organization should be driven by meaning and semantics, and not by technical convenience. Consider what an element means rather than how it looks structurally. Names and locations of templates should be self-evident. Themers want to see markup in templates, not abstraction.

http://www.jenlampton.com/files/twig-sydney-2013.pdf

(For an interesting digression, read Adrian's open discussion of Drupal theming from 2004 and watch Carl's presentation on where we might be going in Drupal 9.)

With the Twig initiative, we don't just see Twig shoved into Drupal core. We also see reduced complexity and improved security. But where is the Twig initiative now? How is the project doing? And what's left to come? I've been tracking the Twig initiative via conference presentations and my own noodling in the code. When I went looking for status updates, however, I got lost.

I find the best place to have real-time conversations in the Drupal community is IRC (https://drupal.org/irc), so this is one of the first places I started looking for status updates. Often I'll just lurk in an IRC channel to get a sense of the conversation. Using the standard naming convention (#drupal-topic name) I jumped into the Twig channel. It was relatively quiet, but I was greeted with a helpful Message of the Day (MotD):

• Topic is {{ url('http://drupaltwig.org') }}
• 2014-03-13 call recording: https://www.youtube.com/watch?v=v043gyl_CXY (does contain occasional swearing)
• 2014-03-13 agenda: http://bit.ly/1ftI2dp
• Next Weekly Meeting (Google Hangout): http://everytimezone.com/#2014-3-20,660,6bj
• Initiative docs: http://lb.cm/twig
• D8 theming docs: https://drupal.org/theme-guide/8

The MotD gave me some excellent insight into the Twig initiative. I started listening to the recording of the past meeting to get a sense of what the "hot" issues are for the team. (The next meeting for the Twig initiative is March 20th or March 21st, depending on your time zone.)

As we approach the end of the Core development cycle, many remaining issues will push developers deep into the weeds. An overview of the remaining issues can be found on the Drupal Twig site. (Remember, completed issues are listed here.)

In the guiding principles, visibility was key. We're supposed to be able to write a theme without needing to read the documentation. And while I appreciate developers who perceive their code to be self-documenting, I don't think people should be required to read it for documentation. So let's dig in and add some starting points for people who are new to Drupal 8.

We know the templates have (mostly) been converted to Drupal 8. We know that when we install Drupal, it looks like it has been themed. So to start truly diving into Twig, the best place is going to be within the core Drupal themes: Stark (minimalist), Bartik (user-facing theme for site visitors), and Seven (administrative theme for authenticated site builders and content managers). We know from the links above that the final resting place for user-facing documentation for Drupal 8 Theming Guide will live here: https://drupal.org/theme-guide/8. But how do we connect the code to the documentation?

Welcome to the documentation team!

All joking aside, we get from code to documentation when people like you and me start poking at things, and writing down what we find. If you have an account on Drupal.org (you should), you're already qualified to be on the documentation team. And as a new member of the documentation team, I encourage you to read the Contribute to documentation page and the Contributing to documentation FAQ.

There are already lots of documentation issues you can tackle, but I'd like to point you toward one in particular. Navigate to this issue and add your wish list of things you'd like to see documented. It's easy. I promise. First log in, then list things that confuse you (or things that you know and want others to know). What frightens you? What are you excited about? I want to compile a giant list of everything you want to learn about theming in Drupal 8. Be sure to read the comments as you scroll to see if others have already mentioned your favorite topics. I've added my top pick to the page already.

Let's start with a list of what we need to document and what we want to learn. Then, together, we'll start turning the code into user-facing documentation. Now go add your comments to the list of topics you want covered in the Drupal 8 theming guide, and check back here for next steps.