Feeds

Author

Jun 10 2019
Jun 10

Hussain began working with PHP in 2001, and at that time, wouldn't touch any CMS or framework and preferred to write his own. He grew tired of issues with PHP and was about to switch to another language when he came across a volunteer project that needed Drupal's capabilities, so in 2010 he tried Drupal 6.

Jun 03 2019
Jun 03

Fresh off the inaugural Flyover Camp, co-organizer Karl Kedrovsky talks organizing local user groups, what it means to give back to the community, and why some furniture is timeless.

You've done it once...you've done it one more time than most people, so you can absolutely give a talk or just share some knowledge on the subject.

May 27 2019
May 27

Cathy Theys could often be found roaming contribution days at DrupalCons organizing people, but she's recently switched gears back to development. I caught up with her in Seattle to find out why.

Somebody showed me that if you help other people in the issue queues, they'll help you back, and that snowballed.

May 20 2019
May 20

For years, SimplyTest.me has provided a once-and-done tool for testing Drupal, and Adam Bergstein has recently taken over maintainership. In this episode we find out why, how you can help, and coffee!

Apr 23 2019
Apr 23

Recent Aaron Winborn Award winner, Leslie Glynn, talks about what keeps her coming back to DrupalCon, her love for illuminating people, and when the heck will Tom Brady retire?

"...to continue learning new things, and that's where you learn, is from the community."

Mar 11 2019
Mar 11

Jim is a Drupal developer at Oak Ridge National Laboratory and has presented several sessions at Drupal camps on a variety of subjects, such as Drupal 8 migration, theming, front end performance, using images in responsive web design, Barracuda-Octopus-Aegir, Panels, and Twitter.

Feb 25 2019
Feb 25

EvolvingWeb Co-Founder Suzanne Dergacheva spills on why she recently joined the Drupal Association, what's happening with Drupal in Montreal, and the Oboe.

Jan 21 2019
Jan 21

Tom Sliker started Broadstreet Consulting more than a decade ago, and has made Drupal a family affair. We dragged Tom out of the South Carolina swamps and into DrupalCamp Atlanta to get the scoop.  How does Tom service more than 30 clients on a monthly basis with just a staff of five people?  His turn-key Aegir platform, that's how!

Jan 10 2018
Jan 10

Have you ever been assigned a ticket with a title like “Some Images Don’t Work,” or opened a monstrous pull request containing a single commit labeled “bug fixes” as your only clue to the changes made? This level of ambiguity is frustrating and can end up costing exorbitant time and money to research. The titles, descriptions, and messages we provide in our workflow should make the jobs of not only our peers easier but also future team members who will inherit the project.

By tweaking our process just a little to document while we work, we can alleviate stress and save time and money on the project. Now don’t go breaking out the wikis and word processors just yet. Much of the critical documentation can be done within the tools you are already using. Writing actionable ticket titles, informative descriptions, and properly referencing related issues and resources can remove mountains of ambiguity and save yourself loads of time filling in the blanks or worse, making assumptions.

Before we get into the details, we need to think about the motivations behind the madness. If we’re going to spend more time writing up descriptions and details, what do we get for it? Anytime you are writing words that another person will read, think about who that person is. It might be a new developer on the team who doesn't have your background knowledge or you in a few months. Maybe a project manager, maybe a stakeholder. Will a machine be able to read and interpret this? All of these factors should influence what you write, regardless of whether it is a description of a bug or a commit message. What information will the next person need so they can eliminate assumptions about the task? Keeping this concept in mind, consider the following benefits:

  • Hours of time spent onboarding a new developer could be reduced.
  • Determining who signed off on a ticket and the process they followed could be done by inspecting a commit’s notes.
  • Changelogs could be automatically generated in different formats for stakeholders and developers.
  • Stop cursing out the previous development team because you don’t understand why they chose a particular method.
  • Or worse, don’t waste your time refactoring that code, then reverting it because you finally did figure out why they chose a particular method.
  • Spend time developing instead of researching a ticket.

As you’re creating a ticket, a commit message, or a pull request; remove the space for assumption. Explain why you did what you did, and, if necessary, how. Let’s start at the beginning with the ticket queue.

Tickets

In this section, we’ll focus on the most granular of issue types: tasks and bugs. Epics and user stories have their own sets of rules and fall outside the scope of this article.

Ticket titles are the first field that someone reads. As I’m looking at my queue, I should know specifically what the ticket is intended to resolve by its title. Consequently, the title should describe the action that the ticket is to fulfill. Here are a couple of examples of good and bad versions of a ticket titles.

Good: “Prevent Nav Bar From Bouncing on Scroll”

Bad: “Navigation is Wonky”

Good: “Implement Home Page Right Rail Promo Block”  

Bad: “Homepage updates”

A helpful hint to consider when writing a title is that it should complete the phrase “This ticket will….” If you’ve done this correctly, the title will always begin with a verb; a call to action. When I see a ticket with the title, “Some Links are Yellow,” I think to myself, “Yes, yes they are. I’m assuming they shouldn’t be since you created a ticket, but what do you want me to do?  Should all links be yellow?  Or none of them?  What color should they be?”  Now, imagine you are a stakeholder reading over a list of completed tickets.  What would you think as you read this title?

Sometimes you’re going to need more than just the title to convey the complete purpose of the ticket, so make sure your ticket descriptions eliminate any room for assumption as well. For bugs, include the steps it takes to reproduce the issue, the environment where you encountered it (OS, browser, device, etc), and what the desired result should be. For simple tasks, reference any comps that describe how it should be implemented and consider user interactions if there are any.  The description field should provide extra information about the goal of the ticket.

If you are having trouble coming up with a specific enough title, consider breaking the ticket down into smaller subtasks, or promoting the ticket to an epic.

Branches

When you start your work, the best practice is to keep your main line of code clear by creating feature branches in your VCS to work on new tickets.  Branches should be filterable, recognizable, and attributable. That is to say, I want to be able to locate a branch quickly by who created it, which issue it’s tied to, and what it’s about.

I prefer a format like this: "owner/issue-id/short-description"

Which could end up looking like: "keyboardcowboy/proj-1234/fix_jumping_nav"

Think about who will see the branch names: myself, other developers, maybe a project manager, the repo gatekeeper if you have one, and machines. Using this format, I can now easily find my branches to create a pull request; I can check if anyone else has a branch for this ticket number; and I can allow project software, such as Jira or GitHub, to reference this branch by searching for the issue number pattern.

Screenshot of someone filtering pull requests in GitHub.Include the username, issue ID, and a brief summary in branch names to make them easily identifiable.

Commit Messages

Developers may recognize the commit message prompt as that annoying thing GIT makes you do before you can push your changes. While it may be annoying when you’re working on your own, I guarantee that coworkers and your future self will appreciate the detailed messages you provide.

The reason for the commit message is to describe the changes taking place in that commit. If you find you can’t describe everything in one sentence, try breaking the commit into smaller, atomic commits. This makes it easier to roll back isolated changes if necessary and allows you to describe each change more succinctly. Just as with the issue titles, describe what the commit does. Someone else should be able to read it and understand to a basic degree what this change encompasses.

It’s also extremely helpful to precede the commit message with the issue number. The software can recognize certain patterns in commit messages and generate links from them. Tools like PHPStorm can help automate this for your process by integrating with GIT.

Screenshot of PhpStorm's commit screen showing automatic commit prefixes.Configure your IDE (PhpStorm shown) to automatically prefix your commit messages with the ticket ID.

Here’s an example of well formatted, atomic commits vs a lazy commit.

Good Commits:

[proj-1234] Refactor white space in CSS so it’s readable.
[proj-1234] Remove deprecated classes and definitions from CSS and templates.
[proj-1234] Increase transition timing on navigation dropdown.

The nav seemed to be jumping when the user scrolled while it was open. Increasing the transition timing allows it to expand and contract more smoothly and alleviates the jumpiness.

[proj-1234] Fix merge conflict in update hook number.

Bad Commits:

Nav stuff.

Notice how the third good commit has multiple lines. The other commits in this set were ancillary to the issue.  The third commit is where the critical changes were made, so I explained my reasoning and why it fixes the issue. Without that, it looks like I just changed the timing. You might be able to trace the PR back to the original issue and piece things together, but a brief explanation directly in the commit can save time and headaches.

It may seem like overkill, but commits become very handy for the next developer, especially if you are using an IDE that integrates with GIT.

Screenshot of a developer viewing a commit's annotations in PhpStorm.Many IDEs (PhpStorm shown) integrate VCS information with each line of a file. Good commit messages are like secret messages to future you or your team.

Pull Requests

Pull requests are a common method to contribute to a project without needing commit access to the repository or to the main code branch.  The title of your pull request should follow the same structure as issues, but with one caveat; like tickets, they should describe the action that will occur if the code is merged, but they should also be prefixed with the issue-id of the issue they resolve. In GitHub, for example, the pattern "#ID" creates a link to that issue number. Even if you are not using GitHub as your issue manager, this is still an important reference, especially if you are running on a standard sprint cycle and need to generate reports for what was completed in each release.  Humans can follow this pattern to reference tickets as well as machines.

When you merge a pull request, a commit is made against the base branch and the title of the pull request is used in the commit message. Wouldn't it be nice if you could search through all the commits between release tags, find any that are pull requests and print them with references to their original issue as a change report? It’s surprisingly simple to automate that process if you follow these guidelines. Here’s an example of a good and a bad pull request title.

Good: “[PROJ-1234] Prevent Nav Bar From Bouncing on Scroll”

Bad: “Navbar Issues”

Imagine reading this as a code reviewer or a stakeholder trying to gauge what was accomplished in the last release. Which is going to be more informative? The title text describes exactly what was addressed, and the prefixed issue number provides the information needed to create a link directly to the original issue.

Just as with the original issue, you have an area for a summary in the pull request. I’ve found the most success in separating business discussions and technical review discussions between the issue management software and the pull request tool respectively. If necessary, provide testing instructions in the proper place and that your team follows any documentation guidelines consistently.

Automated Changelogs

Stakeholders often ask us to provide a list of everything that changed in the last release. Long sprint cycles and large teams can make this a challenge, especially if your issues, commits, and pull requests are vague.  The aforementioned guidelines not only make the project more understandable for people, but also for robots. On a project where the stakeholder required that an email is sent out after every release containing all the changes in that release, we used a simple, custom node script to pull all the commits made between tags and format them into a human-readable list using markdown. That list could be copied and pasted into various places, such as email and GitHub releases.  I’ve found a growing number of utility programs that attempt to do this or something similar. In a single command, you have a perfectly formatted, readable changelog, complete with links to the original issues!

Here are a few helpful tools I’ve found so far:

Documentation doesn't have to be boring and time-consuming. You can clarify your project with just a few simple refinements in your existing process and drastically reduce time spent writing up wiki documentation. Writing more detailed and informative tickets, commits, and pull requests will reduce sunk developer time, provide clarity for your stakeholders, ease your onboarding process, and provide better accountability and understanding throughout the project.

Do you have any suggestions or tips for documenting as you work? I’d love to hear about them!

Oct 27 2017
Oct 27

The first article in this series helped us dismantle the various forms of communication, isolate common pitfalls, and set realistic expectations for the team. Now we'll dig a little deeper and explore effective communication techniques to help stakeholders, managers, and the development and design team work together in blissful symbiosis.

Makers vs Managers

First, we need to agree that all of these groups exist in different realms of the project.  What I mean by this is that each group is involved to a different degree and thus approaches the project with a unique mindset. One of my favorite articles outlining this concept is Paul Graham's 2009 post entitled "Maker's Schedule, Manager's Schedule."

Paul outlines the pitfalls of interrupting a "maker's" schedule with meetings. Managers run on a different style of schedule where meetings and context switching are a regular part of their workday. Makers, such as developers, need large blocks of uninterrupted focus to solve logic problems or hunt down a bug in the system. Remembering, preparing for, and attending meetings pulls the developer out of their "zone." And, as any developer will tell you, getting into that zone is much more difficult than being pulled out of it. This comic beautifully outlines the reason why you should never interrupt a programmer.

Minimize the Meetings

First, I'd like to talk to the meeting schedulers.  As we just outlined, meetings, or as most developers refer to them, "productivity crushing time sinks," are budgetary black holes when it comes to development. A one-hour meeting with a developer could cost two or more hours in productivity when you consider scheduling, prep and loss of focus. Lullabot Senior Developer, Juampy, wrote a great article on reforming this process. So when are meetings OK? Before scheduling one, ask yourself these questions:

  1. Could the information be exchanged via email?
  2. Could this information be rolled into a different, more encompassing meeting?
  3. Do we need to create a deliverable item?
  4. Will all invitees be involved?

I see a meeting being a valuable use of time when multiple people are brainstorming an idea and a deliverable needs to be produced as a result. The keystone of the decision being the interactivity of people. In the scope of a project, a meeting where the majority of invitees are present just to listen is a waste of time. Summarize the information in an email or a document and send it to people to read on their own. If the document is well constructed, follow up meetings and Q&A can be avoided completely and you just saved a boatload of time.

If you have decided that a meeting is necessary, consider who is critical to be involved in the meeting and who could stand to simply receive a summary of the decisions made. Inviting people to a meeting "just in case" is just another time sink. Furthermore, when you involve more people in a conversation, the lines of communication increase factorially, which leads to diluted discussions. Information is more easily processed and decisions made more quickly when there are fewer communication channels.

Graphic illustrating how the lines of communication increase at a much greater rate than the number of people involved.Graphic illustrating how the lines of communication increase at a much greater rate than the number of people involved.

Keeping the meetings to a minimum removes the focus-busting barriers from your production team's workday, but you still need to be in the loop about the project. I've found that most meetings can be easily replaced with email, progress reports, or other project management tools. The benefit to the developers is that they can incorporate these tasks into their schedules in the most effective manner for them. For many stakeholders, however, meetings are how they stay connected to the project. If the meetings go away, other communication methods may fall in to replace them. That's not a bad thing, as long as expectations for how they should be used are set in advance.

Meeting Alternatives

How you structure these ground rules depends on the size and comfort level of both the development team and the stakeholders. A good project manager will sit in between to ensure the proper channels are used and are not being abused. At Lullabot, we often have the entire development team in the same Slack channel as the clients and set up a distribution mailing list for external stakeholders.

Before we get the project up to cruising altitude, we go over the safety speech with the client on how to use these tools effectively. For example, please don't fire off an email for every idea, bug, or individual task that comes to mind. This also goes for Slack pings. Consolidate your thoughts and send them out in a single request. If you truly want to be ignored and miss your deadline, ping the developer every time you send them an email to make sure they got it. Believe it or not, this has happened. Instead, work with the project manager and follow the communication guidelines outlined in the project charter or kickoff meeting. If all else fails, funnel your requests through the project manager and allow them to parse the necessary actions and assign them to the team. We'll discuss more on handling email effectively in the next article.

As a project manager, your place in the communication landscape could be lounging comfortably at the top of the hill enjoying the view, or you might be down in the weeds playing in the dirt. Teams will play nicely together in some projects and could be completely at odds in another. Your job is to keep the information flowing and the project on track.

Set the Ground Rules Early

When kicking off a project, the project manager should get stakeholders, developers, and designers together to discuss the expected frequency of communication and the proper channels to use for certain communications. For example, do you want your developers emailing the clients directly whenever they have a question? Or is it OK for stakeholders to ping developers on Slack every time they find what they consider to be a bug? Defining these ground rules in the project charter or at least in a formal kickoff meeting ensures that everyone is aware of the expectations and the channels are set to make the project run smoothly. It is very easy for clients to feel ignored or developers to feel overwhelmed if neither knows the right method or frequency to address their concerns.

Keep Your Focus  

Check in periodically with both stakeholders and the production team. Ensure the communication channels originally outlined are holding up and important information is not falling through the cracks. Make adjustments if needed, like increasing daily syncs or eliminating useless notifications. It’s easier to begin with fewer items in the communication landscape and add more as needed than it is to try and remove them later, so start lean.

Don't Overcomplicate the System

If you have some excellent communicators on your production team and the client is open to working with them, cautiously step out of the way and let the stakeholders and your team communicate directly. Given this responsibility, you might be surprised at the leaders you have hidden behind the screens. As a project manager, sometimes you can simplify the process by removing yourself!

"Don't add process for the sake of process. The fewer cogs in the machine, the simpler it is to maintain." -  Jerad Bitner, Lullabot Technical Project Manager

For more resources about effectively managing an agile system, check out Jerad’s article, "Lessons Learned in Scaling Agile."

Block Your Calendar

Lastly, here's a little trick for the production team I used when I worked in a meeting-heavy office environment. Coworkers had access to each others' calendars and could thus schedule meetings based on the attendees' availability, so I reduced my availability. I put two giant blocks of busy time over Tuesday and Thursday and made those my heads-down days.

Create full day events in your calendar for uninterrupted work time.Create full day events in your calendar for uninterrupted work time.

This technique funneled most of my meetings into Wednesdays. I saved the smaller tasks that didn't require as much focused brain power to fill in the gaps in between meetings and hunkered down to attack the bigger tasks on those heads-down days. It was a huge productivity boost. Sometimes you need to control the communication flow however you can to get the work done.

We've covered a number of ways that the production team can work effectively with the stakeholders, and also how project managers can help facilitate that. Setting the ground rules early and avoiding unnecessary meetings go a long way to boosting productivity without sacrificing stability. The elephant in the room that we've been tip-toeing around is email. It is by far the most pervasive and invasive form of communication and deserves its own article's worth of attention.  Stay tuned for the next installment, where we'll discuss best practices as well as tips and tricks for dealing with a deluge of email.

In the meantime, if you have any suggestions of your own, I'd love to hear about them! How do you handle complex communication systems?

Oct 20 2017
Oct 20

The key to a successful project is good communication.  Honesty and directness about timelines and scopes of work go a long way to relieve pressure from the development team and avoid frustration from stakeholders, but what about the day-to-day information exchanged between developers, designers, and project managers? This is the grease that keeps the project running smoothly and should not be overlooked.

As teams vary in size, so do the roles and responsibilities of individual team members.  Smaller teams have fewer communication channels, so you may need to switch between your developer hat and project manager hat frequently.  On larger teams your hat rack may be quite sparse, but the number of communication channels, and thus the possibility of miscommunication, is far greater.

Regardless of the size of your team, information about the project must be communicated and documented effectively.  From very large teams to projects where it's just me, I've learned how damaging even minor miscommunication can be.  Conversely, you look like a hero when you get it right.  Stakeholders, project managers, and developers work in very different realms. In this article I'll discuss a few overarching principles that I've learned to help navigate the monsoon of information blustering through a project.  They will help you regain control of your time and create a more productive and successful project.

What is Communication?

Existentialism aside, what do we really mean when we talk about communication?  Communication is an exchange of information between parties.  The parties may be people, but they may also be project management tools.  From video conferences to GitHub notifications, these are all part of the project communication landscape and require different levels of attention.

Forms of Communication

Here are some of the most common methods of communication I've dealt with on projects:

  • In-Person Meetings
  • Voice conference
  • Video conference
  • Chat
  • Text message
  • Direct Email
  • Email Notifications
  • Project Management Tools
  • RSS Feeds
  • Twitter
  • Mobile Notifications

All these types of communication serve a unique role. We wouldn't use them if they weren't helpful, but the question we really should be asking is, "are they necessary?"  Gone unchecked, many of these tools can overrun each other and tangle the workflow.

For example, Slack is a great tool for team members to quickly exchange information between each other, but numerous tools can also post updates into Slack.  A few may be helpful, but too many can dilute the conversation and the effectiveness of the tool.  So how do you find the balance between effective and over-communication?  We can start by categorizing these forms of communication into two groups: active and passive.

Active vs Passive Communication

I find it helpful to group all communication into two categories: active and passive.

Active communication is a two way street.  The sender is expecting a direct response.  Google hangouts, Slack discussions, and phone calls are all forms of active communication.  There is an immediate reciprocation between the parties involved.  You wouldn't invite someone to a conversation just to read them the backlog of tickets, would you?

Passive communication, on the other hand, does not require a direct reply.  This is not as easily definable as active communication.  Let's take a look at email as an example.

If Stakeholder Sarah emails you a question about the next deadline, that is active communication.  She is expecting a response from you in a timely manner.  When a Github notification shows up in your inbox informing you that your pull request has been merged, no follow up is required.  This is passive.  Now, if you receive an email from Jira Notifications because the client asked a question on one of your tickets, which category does that fall under?  It's a notification email, so you shouldn't respond to it directly, but the client is expecting an answer.  Ultimately it depends on the ground rules for communication you set for your project.

Setting Expectations

I tend to follow this order of urgency for response, from most urgent to least.  It's important to agree on a set of communication guidelines at the beginning of a project so everyone on the team follows the same expectations.

  1. Live Communication If you ask me a question face-to-face, of course I will respond to you right away.
  2. Chat Chances are that unless I've set my away message, I'm receiving chat messages in real time.  However, I might be neck-deep in some code or preoccupied in another conversation, so I will respond as soon as I can, but maybe not be right away. 
  3. Mentions in Comments Comments in Jira tickets or GitHub pull requests will likely go unread even if they show up in my inbox unless I am specifically mentioned in them.  I get a lot.  The convention to use the @ symbol to mention another person links their account in the ticket and generates more specific notifications for that person.  It the difference between saying something needs to be done and asking someone to do something about it.
  4. Email I use a couple of email addresses to keep my interests separate so I use an email client to aggregate them into one management space.  However, I find constant email notifications and alerts distracting, so I don't keep my email client open when I don't need to (more on this later).  If you email me, I will probably get back to you within the day, but don't rely on me standing by my inbox waiting to reply to you.  This rule is so important to us that we actually wrote it into the Lullabot Employee Handbook along with a few other tips.
  5. Unmentioned Comments I will likely still get email notifications about activity on repositories, projects or tickets I'm watching or otherwise related to, but if you don't mention me in the comment, it will disappear into tornado of notifications and chances are I won't see it unless I'm reading the backscroll on the ticket.

These are just my rules, but they have worked well for me so far.

Understanding the communication landscape of your project is a necessary foundation.  Setting the proper expectations will prevent miscommunication and keep the project running smoothly.  So far we've identified some of the most common pitfalls and laid the groundwork for a fluid project.  In the next two articles of the series I'll provide advice for managers and stakeholders on how to communicate effectively with the development team and also offer some recommendations and tricks for handling the number one offender when it comes to communication overload: email.

Oct 16 2017
Oct 16

Chris Teitzel of Cellar Door Media gives us a preview of Security Saturday at BadCamp 2017 and provides some great tips for securing your website.  He tells us why we should always say yes to the community; you never know where it's going to lead.

Chris also shares some amazing stories about bringing a Drupal-based communications tool developed from the DrupalCon Denver Tropo Hackathon, to Haiti in 2012 to help with relief efforts after their devastating 2010 earthquake.

Oct 09 2017
Oct 09

In this episode, Chris sits down with Jason Lewis and Stew West of Amazee Labs to get the low down on Drupal Camp Cape Town.  They discuss what it's like organizing a Drupal camp in Southern Africa; convince you to visit Cape Town; and give some thanks to their amazing colleagues at Amazee.

Also, if the internet goes out, keep an eye out for Amazee's (probably) first ever touring Drupal band!

Oct 04 2017
Oct 04

Hailing from Managua, Nicaragua, Mauricio Dinarte takes some time from his pilgrimage across Europe to talk to us about teaching people Drupal from the ground up, no matter what language you speak.

At BadCamp in October he'll be administering a training with Anna Mykhailova from Digital Echidna called "Getting Started with Drupal," then Thursday will be sitting in on the DevOps summit to talk about Behat testing.

If you don't have plans November 17 and 18, you can visit him in Managua at Lakes & Volcanoes Drupal Camp!

Many thanks to Felix Delattre (xamanu on Drupal.org) for giving Mauricio his first big break in Drupal.

Reach Mauricio on:

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web