Documentation and Help Module

Some modules actually don’t require you to do anything — they simply do their job behind the scenes. However, these modules likely don’t have configurable settings or serve only as dependencies for other modules.

Most of the time, the module you’re interested in is something for which you can configure permissions and settings. Some projects are easy to use — they are “intuitive,” and it’s relatively clear what you can configure and what needs to be done to make them work as intended.

If you want to learn all the details necessary to use a newly installed module intelligently, I can think of a few things you might need or places to look.

The following suggestions are listed in order of ease of use.

Unfortunately for beginning end users like us, Drupal is constantly evolving, and while we are lucky to benefit freely from the incredible work of developers, their time is limited. I think it’s safe to say that the best developers aren’t usually the most diligent documentation writers — at least not with beginners in mind. Otherwise, you and I wouldn’t be here right now.

I’d encourage you to document and publish your own trials and challenges while learning to use Drupal — for the benefit of thousands who will be in your shoes in the coming days, months, and years.

This, I believe, is the ultimate goal of creating this documentation, despite (or because of) the seemingly endless annoyances, frustrations, and complications of using Drupal — and of the new documentation section — and in part to reduce the issues of learning and using Drupal, which might have been solved if other beginners like you and me had previously written proper beginner-friendly instructions. But most of all, I’m glad that you, my friend, will benefit from this.

You, like me, don’t need to know anything about “development” or programming to share what you “know” and have learned.

Trial and Error

You can simply dive in and start using the module or play around with its settings.

In cases where you still don’t understand what an option does, or what the consequences might be, just try whatever your adventurous spirit deems best.

Any time you hit a point where using the module involves guessing, don’t be afraid to experiment — just make sure you have a backup of your site to restore if needed. You do back up your site, right?

Since it might not be immediately obvious which features are affected by the module or a particular option, I recommend enabling only one module at a time and thoroughly exploring your site — creating new pages, testing different configurations — before adding another contrib module.

Otherwise, if you enable several new modules at once and encounter strange issues, you won’t know which module is causing them.

Module Project Page

Every module’s project page is its homepage on drupal.org. I usually start there when deciding whether to try a module or when I face issues or have questions about a recently enabled module.

If you read the full project page carefully, you can be reasonably confident you have the most important information. For example, if a module requires other modules to work, they’ll usually be listed there.

The project page may also contain other helpful links and resources related to the module.

The content on the project page may be aimed at new Drupal users or more advanced users/developers.

“Read Documentation” Link (if available)

In the right-hand column (which appears at the bottom on mobile or narrow browser windows), you’ll always find a “Resources” section, where there may be a “Read documentation” link.

However, not all project pages have this link — in that case, hopefully there are other helpful links in the main content area.

When the “Read documentation” link exists, it’s what the developers consider the best resource to start exploring further.

The content of each project page is controlled by the project’s original creator and possibly others they’ve granted permission to.

Other drupal.org users who can’t edit the project page still often create excellent pages with useful information about the module — but sadly, these are rarely linked from the main project page.

Finding those unlinked pages is covered below in the section on Google search restricted to drupal.org ⤵

The Module's "README.txt" File

The “README.txt” file has traditionally been the official location for documenting all critical and required information about the module (or theme), including anything related to updating it to a newer version.

The README.txt file is located in the module's top-level directory after extracting it, if it exists.

To view the README.txt without downloading anything, use this link format:

http://cgit.drupalcode.org/project/PROJECT_MACHINE_NAME.git/blob/HEAD:/README.txt

Replace PROJECT_MACHINE_NAME in the URL with the actual machine name of the module.

The machine name can be found in the URL when visiting a project page on drupal.org, as shown here:

https://www.drupal.org/project/PROJECT_MACHINE_NAME

If there’s no README.txt, the module likely has no settings and works silently as a dependency for other contrib modules.

If there's no README.txt or you want to explore all documentation, use this URL (replacing PROJECT_MACHINE_NAME):

http://cgit.drupalcode.org/PROJECT_MACHINE_NAME/tree/?id=HEAD

In the top-right of that drupalcode.org page, you may need to switch to the core version of Drupal you’re working with.

Google Search Limited to drupal.org

To limit your search to drupal.org, here’s what I do. I use this method often to search drupal.org or any other domain.

I go to google.com ⎘ and type:

site:drupal.org

Note: no space after the colon and don’t use “www.” in the domain name.

Add a space and then type keywords — in this case, the module name.

Sometimes, I also add “Drupal 8” (in quotes) to narrow the results to relevant versions.

To find information about a module across the web, not just on drupal.org, remove the site restriction.

To show 100 Google search results per page instead of 10, click the gear icon at the top right of a results page, select “Search settings,” set “Google Instant Predictions” to “Never show instant results,” and slide the “Results per page” to the far right.

A word of caution: you might be tempted to use the search provided on drupal.org itself, but I’ve found it less useful. Try it if you enjoy frustration.

“Help” Buttons/Links on Your Site’s “Extend” Page (if available)

On your site’s “Extend” page, to the right of each module’s name, you may see the first line of its description if your browser window is wide enough.

Clicking this line expands the full description and reveals buttons/links for “Help,” “Permissions,” and “Configure,” when available.

If you don’t immediately see the description, follow the guide at the module configuration page.

Unfortunately, to access a module’s help page, you not only need to import the module, but it must be enabled — and not all modules have help links. So you won’t know if it exists unless you enable the module first.

For these reasons, I never relied on the “Help” links — although, looking at them now, I see they often lead to useful pages.