Currently, Drupal is a pretty good platform to use as a basis for a variety of mobile solutions. However, the information about this is spread around: docs for a particular module, blog posts, Drupalcon/DrupalCamp presentations, etc.

Proposed resolution

In order to take Drupal to the next level, we need to consolidate and improve documentation around building mobile solutions with Drupal. So let's create a new Mobile Guide that links to all the existing documentation and expands upon it.

Here's the main guide page:

Remaining tasks

  1. Debate and iteratively improve an outline for the mobile guide at
  2. Determine what friendly URL it should have and add it to node #1380356
  3. Build stub pages for all the outlined topics
  4. Flesh out all the pages of the guide with resources
  5. Determine where on the guide should go. Two suggestions have been to be under the “Developer guides” heading or the main “User and Builder Guides” heading.
  6. Review and polish each page in prep for initial public announcement
  7. Update guide home page to remove rough outline and replace with introductory text
  8. Add a link to the Mobile Guide from the homepage
  9. Make public announcement of the new guide
  10. Turn the discussion into a movie script, sell out to Hollywood and learn to surf (i.e. Profit!)

Original report by Eliza411

As part of the D8 Mobile initiative JohnAlbin and I are creating a Mobile guide. I'm opening this issue to verify where to place it.

  • I envision it at root-level, like the theming and multilingual guides, aliased to /documentation/mobile
  • Once it has adequate content, we'd link it on I'm not sure yet if it'll be primarily a developer guide, but that will be well-defined before it gets created, and it would be put in the proper section accordingly.

Does this all sound okay?


eliza411’s picture

Issue tags: +mobile


JohnAlbin’s picture

Even though the Mobile Initiative is focused on Drupal 8, I really envision the D8 initiative as just a facet of making Drupal a leading Mobile CMS platform.

To that end, it's is extremely important that we document the emerging solutions for mobile in the Drupal 7 contrib space. The spectrum of solutions in D7 will inform how we tackle those problems in D8.

Also, people are building mobile solutions NOW. If the Drupal community doesn't make it easy to see how Drupal fits in with those solutions, then Drupal will not be a part of the mobile solutions that people build.

Here's an interesting fact. As of today, there are more mobile users than IE6 and IE7 users. In 3 years, there will be more mobile users than all desktop versions of IE, Opera, Safari, Firefox, and Chrome combined.

JohnAlbin’s picture

Assigned: Unassigned » JohnAlbin

The first thing we'll need is an outline of the kinds of mobile solutions, broken down as detailed as possible.

The outline should focus on mobile problems and how to solve them. The actual Drupal projects involved in those solutions should be secondary.

We need to avoid the "giant list of stuff that's hard to read" problem. So that when there are multiple solutions (and there usually are!) they are grouped together and not all smushed in one long list. (Like the contributed modules's handbooks.)

I think I can handle the initial outline since I've spent the past several months trying to get an overview of the whole problem space.

maerys’s picture

I would love to contribute here somehow. As I am not an accomplished developer, but an »unstudied« Drupal enthusiast I ask you how... So far I worked on several D7 projects creating responsive webdesign themes. But maybe this (i.e. my not technical background) could help avoiding a far too techy approach.

So let me know what I could do.

podarok’s picture

Good news

eliza411’s picture

@maerys It's so valuable to have multiple perspectives on docs. I'm sure there will be a lot of places you can help. Once @JohnAlbin has the outline in place, we'll be poised to really get started.

If you're a willing and able editor, you might review the styleguide while he's working on the outline (if you haven't already).

If you're not the editorial sort, don't let it intimidate you, though!

arianek’s picture

I almost think this might fit better under "Developer Guides" than as a top level section, at least to begin with... since it's kind of a cross reference to a lot of other sections...

If #995370: Want the ability to create multiple outlines/maps ever gets completed, it would solve so many issues on where to put things. ;)

JohnAlbin’s picture

I almost think this might fit better under "Developer Guides" than as a top level section

That would be totally fine by me. :-)

If #995370: Want the ability to create multiple outlines/maps ever gets completed, it would solve so many issues on where to put things. ;)

Agreed. Our biggest problem with the Contributed Modules Documentation, for example, is that its organized by module rather than by solution. We need both.

JohnAlbin’s picture

Status: Active » Needs review

I've created the root page of the handbook and put the outline there. Anyone can edit it. But let's discuss any major re-organization of the outline here.

I've also created a proper issue summary with links to the handbook/outline and a to-do list for the handbook.

JohnAlbin’s picture

Issue tags: +sprint

Tagging this for the D8 Mobile Initiative holiday sprint.

arianek’s picture

Great - I'll keep an eye on here, if you want me to help get it on the docs homepage, let me know!

ckng’s picture

Great start!
Beyond the nuts and bolts, should we include something more important - the content? Providing the best user reading experience independent from the screen size, which could be a list of things to focus on when doing any work on the list.

It should be part of mobile focus, e.g. content-driven design, readability, responsiveness, content layout, typography, etc. Not sure where to fit this in the handbook.

jhodgdon’s picture

Issue tags: +valid issue

Can I make one suggestion: Change the name of the top-level node? The other books on are mostly called "Something Guide", and in general we don't have anything called "handbook" in the Community Documentation any more.

One other suggestion - just in general, make sure your page titles stand alone. That is what people will see first when doing a or Google search. Avoid abbreviations (like "apps") and acronyms (like "RESS") and make sure they can be understood outside the book outline.

Great start and great effort though!

I'm also tagging this issue because we have an issue queue cleanup in effect and this will make sure it isn't "cleaned up". If you have other issues your Mobile group is working on in the Documentation project issue queue, you might add the "valid issue" tag to them too.

You might also want to add your "mobile" issue tag (if it's officially being used by your group to organize issues) to:


JohnAlbin’s picture

Title: Create a Mobile handbook » Create a Mobile Guide on

"Apps" aren't an abbreviation. They are the proper name for applications on mobile devices. But I agree with you that the page titles need to be stand-alone, so I've updated all of the titles in the guide.

I also renamed the handbook to "Mobile Guide".

The pages are starting to have some really useful information. I actually used it yesterday to help me find some tricky CSS needed for responsive embedded videos. However, there's still a lot of gaps we need to fill before we can link to it from the main doc navigation.

What should the permanent URL for this guide be? /documentation/mobile ? /guide/mobile ? /mobile ?

jhodgdon’s picture

In keeping with other aliases like documentation/git etc., and the top-level books listed on /documentation, I think it should be documentation/mobile. If you agree, I'd be happy to alias the page for you (or you can if you have permission). Open to other ideas too. :)

The page titles look good. One might need a slight update: (front end performance)
Maybe it should be "Front end performance on mobile sites" to be more specific?

Also, there's a big documentation effort right now in the Omega theme project that you might want to coordinate with (I know, Omega is not just about mobile but it might be relevant). banghouse is leading (or at least involved with) that effort, and I think they have a sizable team.

jhodgdon’s picture

Issue summary: View changes

Add detailed issue summary

arianek’s picture

Agreed. /documentation/mobile would be the appropriate alias in staying with our existing patterns.

TransitionKojo’s picture

I've seen/heard a distinction made between "feature detection" and "device detection", with the former being the preferred method going forward. If I recall correctly, feature detection is about seeing what a particular browser can do, instead of which browser it is or what device it's running on. In the current outline, the "Mobile/desktop domain switching" and "RESS" sections mention device detection. Should feature detection be discussed/included in one of those sections?

Even if it's already discussed in the "Responsive web design" section (I haven't had a chance to look through ALL those links yet), it seems that Feature Detection (and the distinction between it and Device Detection, which seems to be the incumbent approach) is important enough for mobile that it should be discussed in the other sections.

Of course, if I'm WAY off base (quite possible!) or this has already been covered, somebody just let me know.

jrbeeman’s picture

@Transition, yep you've got that right (re: feature vs. device detection). I agree that it'd be great for the Resposive web design page to have a brief description of the topic, along with links to some related tools like Modernizr.

@JohnAlbin, I like the general structure of this guide with regard to focusing on solutions and keeping away from simply building long lists of links. That said, I think with the Native mobile apps page, it'd be valuable to have a section that's a description of some useful tools for app development. For example, Services and Content API are mentioned under the PhoneGap section, and could instead go in a more general-purpose section. I also think tools like Views Datasource could get a little attention there as being alternative solutions. I'll draft those changes to that page... and this isn't so much asking permission to do so, but more wanting to find out if that style fits with the approach you'd like the handbook to have.

TransitionKojo’s picture

@jrbeeman, glad to hear I got that right! We're in D8 Mobile Initiative Office Hours now and I'm going to start on a "compare/contrast" for Feature Vs. Device detection. It just now occurs to me that I should probably include something about Browser detection in there too. I'm going to start off basic (cuz that's all I've got!), then build from there. I've been wanting to learn more about this area anyway.

@JohnAlbin, I'll have something by the next D8 Mobile Initiative Office Hours at the latest, hopefully sooner.

jefflinwood’s picture

Just updated the guide to include some more information on mobile web application frameworks, including jQuery Mobile

jefflinwood’s picture

Just added some more information about native mobile apps, including mobile application strategy, Titanium, and native capabilities.

TransitionKojo’s picture

I'm STILL not good at this, so I forget to add comments. About a week ago, I added a skeleton for "Feature/Browser/Device detection" in the 'Responsive Web Design" section. I'll be coming back to it, but I'm happy to take ANY comments/suggestions.

Am I missing/overlooking anything significant?

moshe weitzman’s picture

Status: Needs review » Fixed

I'm thinking that this is done. The Guide exists at Everyone is encouraged to make it better.

moshe weitzman’s picture

Issue summary: View changes

Update with new path alias of guide

JohnAlbin’s picture

Status: Fixed » Active

You're right, Moshe. All the remaining tasks were finished. But I realized I missed a few steps for the end of the process which I need to complete.

I've updated the tasks and put this on my to-do list to finish steps 6 and 7 by July 13.

jhodgdon’s picture

Is this ready to be added to yet? How would someone know this guide exists -- it seems to be its own top-level book, but it's not listed on the main Documentation landing page that I can see... Oh, I see -- this is step 8 in the Summary. Anyway, if it's ready enough now, we could add it to the Documentation landing page now...

JohnAlbin’s picture


It's almost ready. But the homepage of the guide is a giant outline instead of introductory text. I'll make sure steps 6 & 7 get done before July 13 and get back to you.

BTW, anyone can do steps 6 & 7. And you'll have my eternal gratitude if you do. (But I can do it before July 13 if no one else does it.)

JohnAlbin’s picture

Issue tags: +mobile-novice

Adding mobile-novice tag

JohnAlbin’s picture

Issue summary: View changes

Add additional to-dos to next steps section

JohnAlbin’s picture

Assigned: JohnAlbin » Unassigned
Status: Active » Needs review

Steps 6 & 7 are completed now.

Which means we ready for "Add a link to the Mobile Guide from the homepage".

Should we add it at the bottom under Theming Guide?

JohnAlbin’s picture

Issue tags: -sprint, -mobile-novice

Removing tags

JohnAlbin’s picture

How about this under the Theming Guide link?

<dt><a href="/documentation/mobile">Mobile Guide</a></dt> 
    <dd>How to build sites to support mobile devices. <em>Audience: site builders, site administrators, designers</em></dd> 
jhodgdon’s picture

Status: Needs review » Fixed

Works for me -- thanks for providing the HTML, so all I had to do was cut and paste. This has been added... I think this issue is completed now?

Go Documentation!!

Automatically closed -- issue fixed for 2 weeks with no activity.

Anonymous’s picture

Issue summary: View changes

Mark 2 tasks completed.

carwin’s picture

Issue summary: View changes

Marked task 9 complete. A link to the Mobile Guide is present on