When the open source WordPress blogging platform first came out, it opened up the world of internet publishing to the masses. Sure, there were website builders out there like GeoCities and Angelfire, but they lacked much and were very ugly. When WordPress came along it gave voice to those willing to overcome the barriers of setting up web hosting and installing the software. These days there are much better website builders for the common person. Squarespace being a standout of the group even has an easy to use e-commerce option. Because of this, the roles of many popular Content Management Systems (CMS)s are shifting.

Matthew Grasmick, grasmash on drupal.org and twitter.com, has written another inspiring post on documentation. As our CTO, Shawn McCabe has often said before, give Acro an easy button, and we’re 100% behind better documentation.

You can read Matthew’s original blog post for a more thorough and somewhat more roundabout explanation of his proposal. Below I’ve edited the heart of his post into 6 distinct proposals and responded to each one.

In general, I think we can all agree the documentation for Drupal has needed a breath of fresh air and is constant source of frustration for new and experienced users alike.

Proposal #1A: Elevate some docs to "official"

Elevate the Drupal 8 User Guide to the status of "Official Documentation"

The idea of creating a tiered documentation has been implemented partially already with the new documentation migration initiative. I think Matthew’s proposal goes one step further by wanting to introduce a new taxonomy term called “Official” for the “documentation page” and “documentation guide” that carries more weight. This idea is very drupally, as we currently do this exact same thing with marking modules as covered by the security policies. Providing a level of assurance that a certain module is produced by people who know what they’re doing and backed up by a team of specialists who voluntarily deal with logistics and other high-level situations.

In general, I think Matthew’s first proposal is a good one. We should implement it by “blessing” certain documentation pages and guides with a stamp of approval / official.

Proposal #1B: Prominently Feature "Official Docs"

Update the UX on Drupal.org to prominently feature the Official Documentation on major site entry points.

Along with the “stamp of approval” we would “red light / green light” these pages. Essentially flagging pages as “red light, unofficial” and “green light, official” would go a long way to signalling to the community at large that we take documentation seriously and only greenlight the best of the documentation.

To take Matthew’s proposal seriously, though, we would also need to implement new call-to-actions on non-documentation pages that point to the “official” pages. Maybe revamp the navigation of header and footer on drupal.org to clarify the difference between “official” documentation and “unofficial.”

Proposal #2: Adopt Best Practices

We should adopt the following as best practices for all Official Documentation:

This is the heart of the proposals. Matthew wants to constrain the carrot, that “official” stamp of approval, through a high-level checklist of best practices. Agreed. Below is a quick run down of the best practices Matthew is proposing.

Let's integrate the semantic versions (8.5.x, 8.6.x, 9.0.x, etc.) into the Official Drupal.org Documentation UX, much in the way that Symfony and Laravel do.

This is absolutely critical but also a huge technical task (high risk). It means that official documentation would need to have it’s status coupled with minor releases of Drupal. The bigger our official documentation grows, the larger the task will be to maintain it adequately between minor versions. I think the manpower needed to make this idea happen might just burn out the individuals interested in stepping up to make it happen. If we, the Drupal community, can stomach the high risk nature of such a claim, then by all means, we need this.

Perhaps a way to reduce risk is to “evergreen” stamp certain pages, clarifying the fact that certain pages would not likely need updated between minor releases. We could also reach out to Symfony to ask how they manage minor releases and documentation.

Proposal #4: Lower Contribution Barrier

Lower the contribution barrier.

Decoupling the documentation contributors could impact the early adopters positively and long term users negatively. I think think the primary way to achieve the goal set out in this proposal is tightly coupled with the next proposal, by letting users of an open source git-powered platform make the edits, we essentially open source our documentation and our processes at the same time.

I helped spearhead the move of Drupal Commerce’s documentation to the subdomain “docs” for the same reason. We have much better documentation because of this move. Anecdotally, for Drupal Commerce 1, we had maybe a handful of contributors to Drupal’s documentation. Now, for version 2, we have a myriad of contributors (51!!). Scaling documentation is hard, and this is one way to increase involvement.

Personally, I absolutely love this part of Matthew’s proposal. Professionally, I think the community is divided and people are picking sides. They are rightly asking: Why can't Drupal do this very content heavy thing better? Perhaps the answer is: Drupal can do this! We just have to accept this content lives in a version-controlled repo and not in the database.

Proposal #5: Host Docs on Repo

Use a repository that is hosted on GitHub (or GitLab) to manage the official Drupal documentation.

Agreed. I’m looking forward to learning how drupal.org will move to one of the git-based hosting services. I’d throw my hat into the github arena, but the initiative for drupal.org has already chosen bitbucket. So let’s use bitbucket.

Proposal #6: One Pager

Create a new class of documentation that we're lacking: "The Official One Pager."

Cool, love the idea. I think we could take or leave this. If I were proposing these changes to a client, I would mark this proposal as optional. This helps communicate that this proposal is a lower priority (unless the decision makers want to make it a higher priority) and helping the decision makers understand that this scope increase, while very beneficial, would impact the delivery and bottom line and could easily be moved on to a different delivery schedule.

Integration of CRM tool with web applications has turned out to be an undaunted task especially when you monitor/manage your contacts, existing clients and leads generated for marketing campaigns. In this post, I would like to walk you through Salesforce integration with Drupal web application. Let’s dive in to the basics of Salesforce.

Salesforce is a cloud-based CRM solution that helps business effectively manage sales, service, marketing, collaboration, analytics, and building custom mobile apps. In order to manage the business effectively, companies need to integrate their Drupal website with Salesforce CRM solution, which…

If you're familiar with the Urban Hipster Drupal Commerce demo site, you may have come across the UH+ Axe product page and wondered how it was built. Well, today I'll give you a bit of a technical demonstration on how it was created, what modules were used, and some of the custom work that went into it.

The Urban Hipster Drupal Commerce 2 demo site showcases what the Commerce 2 module can do basically out-of-the-box, with added theming and configuration. The product pages within the demo are setup in a way that rivals any other ecommerce platforms, and this suits most ecommerce store owners who want to show a whole bunch of different products in a familiar way.

However, there are cases where you might want a fully custom product page that is an experience all in itself. Apple is a good example of this. Viewing an iPhone on the Apple website isn't just a cookie-cutter product page, it's full of content and rich graphical elements. The page itself is a powerful marketing piece. The Apple website wasn't built on Drupal, but the flexibility that is the Drupal platform allows us to do much more than just the standard. The UH+ Axe "builder" type of product page was created to show just that, how you can push the boundaries with your Drupal Commerce product pages.

For the past two minor release Drupal core upgrades, I've had major problems trying to get some of my Composer-based Drupal codebases upgraded. For both 8.3.x to 8.4.0, and now 8.4.x to 8.5.0, I've had the following issue:

I have the version constraint for drupal/core set to ~8.0 or ~8.4 in my composer.json.

On a recent project I wanted to be able to create a custom field which would automatically be added to certain types of entities. I thought that this would be a straightforward thing to do.

When I searched the internet for how to create custom fields I found plenty of documentation on Drupal.org and other blog posts about creating custom fields that you can add to any type of entity, but I couldn’t find out how to actually add the field directly to an entity (like the URL alias field).

You need to create a FieldType plugin, a FieldFormatter plugin and a FieldWidget plugin in a custom module. Combined, these define your field, how it will be rendered when displayed, and what settings a user can set on it when adding it to an entity.

The directory structure of a module that implements all three looks like this:

my_custom_fields

my_custom_fields.info.yml

src/

Plugin/

Field/

FieldType/

MyCustomFieldItem.php

FieldFormatter/

MyCustomFieldFormatter.php

FieldWidget/

MyCustomFieldWidget.php

I would recommend reading the documentation about these as there are some great examples as to how they can be defined.

Adding your field to an entity.

So having now defined your own field, you should be able to see if in the list of fields that you can add to an entity.

Great, you think, I've done it! Well, if all you wanted to do was to create a field that you could add to any type of entity if you choose to … then yes, that's all you need.

However, I wanted to automatically add my custom field to an entity when my module was enabled. This was because I wanted there to only be one instance of my field on an entity, so there was no need to be able to add it manually (a bit like the URL alias field).

Automatically adding your field to an entity.
If you want to be able to add a field directly to an entity, you need to use hook_entity_base_field_info for this. For example:
use Drupal\Core\Field\BaseFieldDefinition;
/**
* Implements hook_entity_base_field_info().
*/
function my_module_entity_base_field_info(EntityTypeInterface $entity_type) {
if ($entity_type->id() === 'taxonomy_term' || $entity_type->id() === 'node') {
$fields['my_custom_field'] = BaseFieldDefinition::create('my_custom_field')
->setLabel(t('The custom field))
->setDisplayConfigurable('form', TRUE)
->setDisplayConfigurable('view', TRUE);
return $fields;
}
}

You'll notice in the above example that this uses the BaseFieldDefinition class to create a new base field only on taxonomy or node entities. More information on this hook and the BaseFieldDefinition class can be found in the Drupal.org documentation.

So now we can add our custom field to specific entity types - amazing! At this point I thought I'd cracked it. Having cleared my cache I checked my entity and there was my custom field with the widget showing as I'd expected. But when I came to save my entity, the save failed with this big exception:

Drupal\Component\Plugin\Exception\PluginNotFoundException: The “my_custom_field” plugin does not exist. In Drupal\Core\Plugin\DefaultPluginManager->doGetDefinition() (line 52 of core/lib/Drupal/Component/Plugin/Discovery/DiscoveryTrait.php)

Having had a play about to see what was causing this, it seemed that because I had specified to create a base field of ‘my_custom_field’, Drupal didn’t understand what this field was.

There are lots of defined field types already with Drupal but, as I'd created my own, Drupal didn’t know about it.

So I set about trying to understand how to define my own field type.

I got nowhere at first so I turned back to Drupal core and started delving into the base field definitions to try and understand how these have been defined.

What I found was that I need to create a DataType class which defines my custom field. This class needs to be located within the Plugin directory of your module, for example:

This new DataType class extends the StringData class as I am just storing a string. If you wanted to store a boolean or integer then you would need to extend the relevant DataType base class to make use of all the goodness that they set. If you want to override any of the methods on these classes then you can as normal.

So now Drupal understands what my base field of ‘my_custom_field’ is.

But wait - we're not quite finished yet… Although the entity will “save”, you will notice that no data is actually saved for my new field yet. This is because we haven’t defined the storage for it.

There are several ways in which you could handle this. You could define your own database table and then write to this as part of the preSave method on the FieldBase item.

The easier way is to define your own config entity which will add additional columns to your entity table to store your custom data against. To do this, you just need to create a schema.yml file in your module, for example:

Why Drupal needs the benefits of marketing
Michel van Velde, CEO and Co-founder of One Shoe
Drupal has no professional marketing team, unlike many competitors, do. Any brand which doesn’t promote itself has weaker sales. And that includes all of the brands, even the biggest and established ones. If the marketing stops, so does the sales. But how do you promote Drupal without its marketing team? Michael van Velde, CEO and founder of One shoe, explains why Drupal needs marketing from a business point of view on one hand and developers point of view on the other and gives examples… READ MORE

It’s no secret that diversity in the overall tech world is dismal, with it being overwhelmingly white and male. While we still have room for improvement, Palantir.net is proud to have a diverse staff that is more than 50% women (with gender balance at all levels of the company), and we are also diverse along other dimensions, such as race, ethnicity, sexual orientation and identity. One of Palantir’s core principles is that we believe that the best outcomes are realized when people are able to create and collaborate in an open and inclusive environment. While we are only a small company, we believe everyone has a role in helping to promote diversity, inclusion, and equity within the technology industry.

One of the places where we can make a difference is in the Drupal open source community. Palantir team members have been involved for years in efforts to help to make Drupal more welcoming and inclusive for contributors already in the community, but most people outside of Drupal have never heard of Drupal! So we decided to be a bit more proactive in exposing the possibilities of Drupal to a more diverse crowd by reaching out and pulling some talent into our community.

The Idea

At MidCamp 2017, Chris Rooney of DigitalBridge gave a talk that asked the question about how can we as a community bring more diversity in? I approached Chris after his talk and had a simple solution (in theory): DrupalCon Baltimore was just three weeks later . . . why don’t we find an organization with which we can partner and invite some students to attend DrupalCon for the day?

Due to some serendipity on our end with her being between projects, my colleague Michelle Jackson — a Strategist with a background in youth education who also happens to live in Baltimore — was able to help me find 5 students from the Baltimore chapter of NPower to join us at DrupalCon. With three weeks and much help from within the Drupal community with providing extra tickets, a room at the conference, and their time in speaking with our group, our five students had a quick introduction to Drupal class in the morning led by Ryan Price and Digital Bridge, followed by lunch with various members of the community, and lastly time in the afternoon to attend sessions and walk the exhibit hall.

After DrupalCon Baltimore was over, we asked ourselves how we could expand on this initiative, and what that would look like. Do we keep just offering one day of exposure? Do we try more formal Drupal training? What are the logistics involved? What are the obstacles?

There were limitations to doing just one day of exposure at DrupalCon: with only a few hours, we couldn’t give more than a basic intro to Drupal, so we focused more on an overview of open source and career paths into Drupal and the web. It was enough to get the students interested, but felt too abrupt: after all, the students went from having never heard about Drupal, to being thrown into a DrupalCon conference with all of its jargon and high-level sessions. We decided to expand the program into a longer-term one that began with basic training, building a project slowly over a few months, thus allowing them to attend DrupalCon with more context and to possibly find an internship at its conclusion.

Other logistics we had to consider: we couldn’t assume that all students had laptops or access to internet, the amount of time Palantir staff had to devote to training each week (let alone planning), scheduling times to meet, and costs involved with getting students to conferences.

Our Inclusion Initiative

Now one year later, we have our first pilot class of students who just this past weekend joined us at MidCamp in Chicago, and will be joining us at DrupalCon in Nashville! Our program looks something like this:

We expanded from five students in 2017 to eleven for 2018. Two students dropped out of the program due to interfering outside forces, so by MidCamp we had nine students heading into DrupalCon.

We partnered with NPower in Baltimore again, since three of the original students were still interested in learning about Drupal. We also brought in Genesys Works from Chicago for the other students. As Palantir is a Chicago-based firm, it made sense to have some of the talent be local to us.

We partnered with FigLeaf in Baltimore to provide weekly training. Dave Gallerizzo met with students remotely via Adobe Connect to teach an hour-long class to our students.

Each student picked a personal project to build. These included an NBA fan site, a mariachi site, one for a church, one for music, and one for an upcoming video game release.

Starting with a kickoff on January 6th, 2018, we began the weekly classes. Palantir gave a refurbished laptop to each student, we set everyone up on a Slack channel, and started our first Drupal class.

We also found mentors within the Drupal community to donate an hour of their time every week to work with our students during, “lab hours,” and invited them to the Slack channel. Students now had one hour/week of class, plus one hour/week of lab hours with a mentor.

The students met in-person at MidCamp in Chicago so they could review their work, attend sessions, and meet others in the community.

Looking forward, the students will continue working on their projects until we all meet again at DrupalCon Nashville to review their projects.

After DrupalCon, Palantir will assist with resume creation and helping students get internships within Drupal.

So here we are, just after MidCamp, and so far so good. The students were able to meet each other, show progress on their work, see a number of sessions, meet the community, get hosted on Pantheon sandboxes, and are ready to keep going towards Nashville!

While we did a lot of things right, our program isn’t yet perfect. While the students enjoy the flexibility of the recordings and being able to check in with mentors as needed, they’ve also let us know that they’d prefer more overall structure to the expectations for each week. They also said they would have appreciated more of a breakdown of the types of work on which they could focus (security, front-end development, design, strategy, etc.) so they could anticipate which sessions fit their interests. Great feedback for us as we move this forward.

“I’ve learned a lot to help me on what I’m working on with my project. By DrupalCon, I should have extensive information on all the ways to use Drupal.” - Blake James, NPower student

What did it cost?

This wasn’t free, of course. Here’s an outline of the general costs.

The Hard Costs

Palantir spent about $8,000 in travel costs between flights, hotels, and meals.

The Larger In-kind Donations

FigLeaf training classes and materials, totaling about $11,000

Palantir provided a refurbished laptop to each student, valued at about $3,200 total

Mentors and Palantiri donated time in mentoring students weekly (about 1 hour/week)

Palantiri donated time in organizing the program

Free subscriptions from Drupalize.me and Jetbrains (PHP Storm)

Ticket donations for MidCamp and DrupalCon from organizers and community members

It Takes a Village

This didn’t happen in a vacuum, and took the help of many people to make it happen. A HUGE thanks to the following, who contributed in ways both large and small.

Mentors

Damien McKenna: Mediacurrent

Dave Terry: Mediacurrent

Melissa Bent: Mediacurrent

Chris Zeitlow: MindGrub

Michelle Jackson: Palantir.net

Ryan Price: Palantir.net

Jes Constantine: Palantir.net

Hannah Rosenburg: Digital Bridge

Ryan Peters: Digital Bridge

Tara King

Sherry Sonnier-Johnson: Sealed Air

Rob Powell: Mass.gov

Organizers

Allison Manley: Palantir.net

Michelle Jackson: Palantir.net

Ryan Price: Palantir.net

Megh Plunkett: Palantir.net

Lauren Burroughs: Palantir.net

Michael Dickey: Palantir.net

April Peck: Palantir.net

Colleen Carroll: Palantir.net

George DeMet: Palantir.net

Annie Schow: Palantir.net

Chris Rooney: Digital Bridge

Dave Gallerizzo: FigLeaf

Julia Logan: Genesys Works

Cathy Morgan: NPower

Additional Support

Drupalize.me

MidCamp volunteers

Drupal Association

Steve Persch

Dwayne McDaniel

Pantheon

Acquia

PHP Storm

Digital Bridge Solutions

Amanda Gonser

Tim Plunkett

David Hwang

Jason Yee

Andrea Soper

Ashleigh Thevenet/Bluespark

What Can You Do?

This is only one idea to address the diversity problem. We certainly encourage you to find other ways that work better for you. But we also encourage other digital agencies to follow our playbook and proactively look for talent to develop and bring into Drupal and other open source projects. The talent is out there, but we can’t sit back waiting and hoping they will find us. We have to invite them in to the opportunities. Both NPower and Genesys Works have several local chapters nation-wide, and our contacts at both organizations would be happy to work with you to find the right talent.

I also hope that the students themselves decide that Drupal is appealing to them, and that they can get some internships within the community. Get ready . . . they are polishing their resumes to hand out at DrupalCon! If you’re attending, please consider meeting with them in Nashville to talk about hiring opportunities. If you’re not attending and are interested in hiring one of these students, please contact me (manley@palantir.net) so I can connect you with a motivated intern who is ready to learn more about Drupal.

Students meeting up in Chicago.The group having dinner at Portillo's during MidCamp.

There will be a security release of Drupal 7.x, 8.3.x, 8.4.x, and 8.5.x on March 28th 2018 between 18:00 - 19:30 UTC, one week from the publication of this document, that will fix a highly critical security vulnerability. The Drupal Security Team urges you to reserve time for core updates at that time because exploits might be developed within hours or days. Security release announcements will appear on the Drupal.org security advisory page.

While Drupal 8.3.x and 8.4.x are no longer supported and we don't normally provide security releases for unsupported minor releases, given the potential severity of this issue, we are providing 8.3.x and 8.4.x releases that include the fix for sites which have not yet had a chance to update to 8.5.0. The Drupal security team strongly recommends the following:

Sites on 8.3.x should immediately update to the 8.3.x release that will be provided in the advisory, and then plan to update to the latest 8.5.x security release in the next month.

Sites on 8.4.x should immediately update to the 8.4.x release that will be provided in the advisory, and then plan to update to the latest 8.5.x security release in the next month.

Sites on 7.x or 8.5.x can immediately update when the advisory is released using the normal procedure.

The security advisory will list the appropriate version numbers for all three Drupal 8 branches. Your site's update report page will recommend the 8.5.x release even if you are on 8.3.x or 8.4.x, but temporarily updating to the provided backport for your site's current version will ensure you can update quickly without the possible side effects of a minor version update.

The Security Team or any other party is not able to release any more information about this vulnerability until the announcement is made. The announcement will be made public at https://www.drupal.org/security, over Twitter, and in email for those who have subscribed to our email list. To subscribe to the email list: log in on drupal.org, go to your user profile page and subscribe to the security newsletter on the Edit » My newsletters tab.

Journalists interested in covering the story are encouraged to email security-press@drupal.org to be sure they will get a copy of the journalist-focused release. The Security Team will release a journalist-focused summary email at the same time as the new code release and advisory.

At Lullabot, we’ve been using Agile techniques for years to help run our software projects. We’ve learned what pieces of Scrum and Kanban seem to fit our teams and what parts are safe to ignore. We’ve learned not just how different Agile methodologies prescribe we should work, but we’ve uncovered what’s actually helpful to us. In other words, we have opinions.

One of those opinions really crystallized among our project managers over the last 12 months, and we want to share it with you. It has to do with the way we think and communicate about the work that our teams do.

User stories

Most of us in the software industry have encountered the idea of user stories. These minimalist requirement statements have been around for two decades, and are one of the fundamental ideas in Agile software development. As such, there’s been a lot of thinking and discussion around them.

Rather than being some definitive statement on user stories, this article is a reflection of the experience of working with this kind of artifact within the specific context of our clients, developers, and project managers here at Lullabot.

A user story is supposed to be a short statement about a task a user wants to do with a particular software. It briefly describes the user, the task, and what benefit the user gets from it.

On typical format of a user story looks like this:

As a <type of user> I want to <do something> so that I can <benefit>.

A more concrete example would be:

As a Night Owl, I want to drink multiple cups of coffee in the morning so that I can be even slightly functional before noon.

Or:

As a visitor to this website, I want to easily search for content so that I can find what I’m looking for quickly.

The brevity of this format is helpful to force people to have actual conversations about the feature they’re building. Once upon a time, development teams and business stakeholders needed to be encouraged to collaborate more, so this was a revolutionary tool.

So, obviously, this is a good idea. But In the course of the last year, we talked about user stories a lot and how they can help or hurt a development project.

Is everything really a story?

Stories are such an operating assumption that many of the software packages that help organize development projects start with ‘Story’ as a default issue type. They’re so normalized in modern software that we’ve even had clients direct us that “everything needs to be a story” in their projects.

Explicitly or implicitly, there’s an idea out there that since we’re Agile (whatever that really means), we have to do user stories for everything. I’ve found myself writing 'As a user' stories uncritically, out of habit, or because I was instructed to do so.

However, there’s often business-driven or system-level requirements, which are not user-focused at all, that have to be crammed into the user story format. It’s easy to apply the user story format to everything, for the sake of consistency, but it’s a bad fit in several common cases. Here’s an example of a technical requirement stuffed into a user story:

As the system, I want to verify a user's OAuth credentials before granting access so that I can ensure secure connections.

I’ve seen and written lots of stories like that. The problem is that this story personifies the system with wants and desires which it does not have. If it were truly a user story, the user would be the focus like in this example:

As an amateur chef, I want to log into the system because I want to access recipes behind the paywall.

You’ll note that the whole character of the story has changed. Security and technology standards are not the primary concern of the user, so they aren't reflected. It doesn't reflect the business requirement of HOW the authentication should happen, but then again the user doesn't care about that. It’s honest but less than effective as a requirement.

As a user, I want you to take my money

This is also a problem for business requirements that are not actually user-focused. They are similarly ill-suited to the user-story format:

As a site visitor, I want to see advertisements so I can know about products and services that might interest me.

We know that no user ever wanted that. They came to the website for the content, and the advertising was a distraction. So that user story is fundamentally NOT about the site visitor—it’s about the revenue model of the site.

User stories function as conversation starters about the value of a piece of work and the ways in which that value might be realized. Our examples above don’t need conversation or discussion. The imperative and authority to do the work come from the organization’s need to provide security or earn revenue.

So how do you express non-user requirements?

In general, it’s better to surrender to common sense and not put these kinds of technical requirements into the user’s voice. Instead, write simple, imperative statements that declare what must be done.

Integrate Google AdSense into article pages.

Require a valid OAuth token for access to the system.

We like to surrender to the forces of common sense and call a user story that no longer involves a user what it actually is: a task for a developer to perform.

This might seem like a meaningless distinction—who cares if it’s a story or a task or whatever? But if your mental model of the user is demonstrably false, what else are you getting wrong?

It’s easy to write your biases into the user’s voice and finding yourself keeping the status quo instead of doing something new. If you insist on shaping the conversation around your product from a false premise, how can you spot your real business problems and innovate to solve them?

To take our example from above, maybe traditional web advertising is a sub-standard way of generating revenue for your business, but you’ll never have that conversation if you paint it over with false user requirements and benefit statements.

What are user stories actually good at?

The beginning of our process is a well-written, truthful story about a feature with benefits for specific kinds of users, accompanied by clear acceptance criteria.

Ideally, we’re starting from a position where there’s been actual user research and one-on-one interviews during the discovery process. That ensures we’re building features that users are actually interested in.

As a content administrator, I want to be notified of new user account requests because I need to review and approve them quickly.

As an authenticated user, I want to drill into search results using facets because I’m looking for something very specific.

As a vacation planner, I want to visit a page that aggregates content about my country of interest, to help me decide what I might like to do while in that country.

The conversation around actual user-based stories builds understanding between the business and our development team, and it sets us on the right path. It just needs to be recognized that the user story format itself isn't magic.

The life-cycle of a story

It’s natural that stories would be initiated by the business stakeholders based on their knowledge of their users. In the same way, when the developers are done with their work, those same stakeholders will want to verify that the story is properly complete.

That makes stories an ideal artifact to drive QA and acceptance testing. Developers and QA team members both benefit from business-level acceptance criteria elaborating the story to help guide their work.

We like to use Gherkin as a way to write acceptance criteria using a particular format consisting of ‘Given, When, Then’ statements.

Given expresses the preconditions of the acceptance criteria. This might be authentication, the existence of some data, or the completion of a business step that must precede the feature under discussion.

When expresses the action a user takes.

Then expresses the result of the action.

All three of these keywords can be combined with conjunctions like ‘and’ or ‘but’ to layer conditions onto the acceptance criteria. Here’s a simple example:

Given a user has requested an account in the system,

and the account request has been reviewed by an admin,

and the admin wishes to approve the request.

When the admin approves the request,

then the account changes state from ‘pending’ to ‘active,’

and the user is notified by email that their account request has been approved.

This kind of acceptance criteria is great to work up as the story is being discussed, where developers can ask questions of business stakeholders. Gherkin is actually used in software like Cucumber and Behat to drive automation of these test criteria.

Not every client is interested in this kind of test automation, but even if those tests will never end up in code, working with Gherkin to write acceptance criteria has a way of clarifying everyone’s thinking.

When the conversation is done

The story and the acceptance criteria are really valuable for everyone involved. But, when you’ve reached a stopping point and the story is ‘ready for development,’ there’s still more that has to happen. Even with great acceptance criteria, the story still might not express the level of detail that a developer needs.

Beyond the story and acceptance criteria, developers may rely on technical documentation, design artifacts, or architectural planning to fill in the gaps. This is especially true when a story is a single unit of value to the business, but the implementation crosses disciplines and teams.

Stories for everyone, subtasks for developers

It’s helpful at that point to break the story into subtasks which can be assigned and sized for an optimal developer workflow — bite-sized chunks that take no more than 1-2 days to accomplish, and which are often unit testable but aren't always good candidates for QA.

Our account approval example from above can be broken into several tasks. Most of these features are off-the-shelf with Drupal, but we’d probably want to make some adjustments and customize the language in the notification emails.

Again, our task format is short imperative statements, possibly with additional notes as needed in the body of a ticket.

Grant permission to site admins to allow account approvals.

Build a list of open account requests.

Customize account approval emails.

You may or may not need distinct acceptance criteria here. Some tasks are self-explanatory, while others have the need for more guidance as we describe above.

In any case, QAing these shorter tasks can be cumbersome and confusing for the QA team because the total work for that story is not sufficiently complete. Any single task is only part of the full acceptance criteria, and they’re often interdependent.

However, we’re not without validation for those subtasks. Unit testing and peer review between developers work very well for checking them along the way, especially when we write custom code where errors might be introduced. When all the tasks are done, the complete story can move forward to QA and acceptance testing for the complete feature.

All of this is to say that user stories are an important part of Lullabot’s software development process—but they’re not the only thing we need to get the job done.

Get more background

I like to know the background and history of these techniques we use to manage our projects. The user stories and Agile development practices have been around for about 25 years, but it sits in the context of the whole history of software. Knowing the history and the thinkers behind it all set you up to use the practices selectively and use them well.

In that light, and to give credit where credit is due, these are some of the folks that did the big thinking around user stories and other Agile practices. If you’re a practitioner of Agile in some way, check out their history and opinions:

In my last post “Untapped Areas for Business Improvements” I attempted to point out the various areas where the potential exists for significant returns for your business through intelligent work automation. As well, time was given to examine some of the more obvious impediments as to why so little is done in this area.

I would like to take the discussion to the next level in reviewing the potential for rewards. No one is going to make intelligent work automation a priority unless there is some ‘gold’ to be discovered. The key to this is centered on employee productivity. And while I will dedicate most of this article to the rewards, we also need to look at what is at stake by ignoring these suggestions and doing nothing.

Drupal Europe promises to be the most significant community lead conference in the history of Drupal on the continent. Redefining and reinvigorating what a major Drupal conference means to the community, business users and agency leaders Drupal Europe promises to be an exciting and rewarding experience.

That post sparked a tremendous degree of engagement. Many people commented, wrote responses on their own blogs, and voiced support on twitter. I was pleasantly surprised by the Drupal community's response, which was (nearly) uniform and highly corroborative. The jury is in. Drupal's evaluator experience is fraught.

What should a dream theme for a Drupal 8 website be like? Responsive, modern-looking, highly customizable, rich in powerful features, and intuitively understandable, perhaps? Many developers would say a dream theme is based on the Bootstrap framework.

Managing Drupal sites with composer brings a number of benefits. However, when installing Drupal dependencies from source (an option offered by composer), you also lose the functionality provided by Drupal core’s “Available Updates” page. Thankfully Composer will allow you to keep tabs on the available updates for all of your project’s dependencies, including Drupal core/contrib.

Support the game designs and theoretical work of As If Productions. Written especially for roleplayers, GMs, game designers, artists and neophiles who are interested in experimental applications of narrative engineering.

"Most people think that the things they experience are real... But they are wrong... This can be seen as an illusion if we go to a different culture, or if we enter a different reality by going insane."