Now that the User Guide is published and ready to be promoted I think we should start by re-thinking the top level /documentation page in order to promote the user guide as the entry point for new users. As well as providing a more intentional design/layout for the rest of the landing page.

Page in question: https://www.drupal.org/documentation

So I guess the question is; What does a new/improved version of the main documentation landing page look like, and what purpose does it serve.

Question for the DA. Was there a design already created for this page as part of the overhaul of the documentation section?

My initial thought it something like this:

+---------------------------------------+
|                                       |
|    User guide                         |
|                                       |
+---------------------------------------+
|   D8      |    D7     |  Developers   |
+---------------------------------------+
|                                       |
|  Other                                |
|  - item one                           |
|  - item two                           |
|                                       |
+---------------------------------------+

Where the User Guide always points to the latest version of the guide for the current version of Drupal. The D8/D7 are always links to the documentation for the current, and previous versions of Drupal.

I think promoting the user guide is beneficial for a few reasons. It's high-quality, and makes a good first impression for people who are new to Drupal. It servers as a great "Start here" call to action for both new users, and people who are evaluating Drupal.

Remaining tasks:

  • Agree on layout of page
  • Create a new design for the page
  • Implement new design

I also think that in the interm we should edit the page and add a link to the user guide much like the existing Drupal 8 / Drupal 7 links. Otherwise there is no good way for users to navigate to the guide until we redesign this page.

Comments

eojthebrave created an issue. See original summary.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

+1 for the proposed layout, or something similar...

Also I noticed on /documentation currently, near the top, there is a link for the Site Building Guide. It seems a little bit orphaned, like it should belong either under D7 or D8? Or under a different heading?

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented

The orphaned site building guide is a result of the in-progress migration. Once all of the content has been moved to the appropriate D8 or D7 section it should go away.

tvn’s picture

tvn CreditAttribution: tvn at Drupal Association commented

I think it is a great idea to promote User Guide in various ways, and we do need to redesign landing page once the migration is (mostly) done into the new section. I think those are two different discussions. E.g. we need to design the new landing page even without User Guide happening. At the same time, we can promote D8 user guide in more ways and in more places than just front page. I've been meaning to open an issue for the new landing page design for sometime, so we could discuss. I opened it here #2828874: Design top level landing page for the new documentation system. I suggest we keep this one to 'promote D8 user guide', which might happen in more places than front page.

Was there a design already created for this page as part of the overhaul of the documentation section?

There were some ideas/assumptions/early wireframes, which need update. I'll share in the other issue.

The orphaned site building guide is a result of the in-progress migration. Once all of the content has been moved to the appropriate D8 or D7 section it should go away.

That is correct.

On the topic of promoting user guide. I added a link to it to the current /documentation (feel free to modify description), and https://www.drupal.org/docs/8.
I think on https://www.drupal.org/docs/8 we could make it even more prominent, if you could give me a couple of sentence copy to put in a block e.g. in the sidebar.

What are some other things we could do to promote it?
Some ideas include:
- tweets,
- include in newsletter
- link from other places on D.o, e.g. general documentation

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Title: Clean up /documentation and promote new Drupal 8 User Guide » Promote new Drupal 8 User Guide

Sounds good on splitting; updating title of this issue accordingly.

Thanks for adding it to
https://www.drupal.org/docs/8
https://www.drupal.org/documentation
Both look good to me as they are... if you want to put more in the sidebar on docs/8, you could add the blurb from /documentation that says:

Curated introduction to readers new to Drupal 8.

Actually I think maybe I would change that to something more like:

Guide to installing, building, and administering a Drupal 8 site, aimed at readers new to Drupal.

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented

Okay cool.

Any objections to moving the User Guide to the top of /documentation? So the order would be

- Drupal 8 User Guide
- Drupal 8 Documentation
- Developer Documentation
- Drupal 7 Documentation

I think that better reflects that order that someone new should encounter those things. And, that anyone for whom /documentation isn't new they've probably already got a pretty good idea of where they are going and don't need the same kind of visual hierarchy.

As for other places to promote the user guide, I'm mostly interested in long lasting solutions that help people who land on various pages on Drupal.org discover the guide. Sort of a call to action to read the guide if you're just getting started with Drupal. Do we have any sense of what might be common places for people who we're trying to help make the transition from learner to skilled (https://www.drupal.org/drupalorg/personas) often start from. Or maybe where they commonly get lost?

This probably also means promoting the guide on places like Slack/IRC and Stack Exchange. I'll keep pondering.

As for Twitter, I could see it being useful to have a semi-regular post scheduled that points people who are getting started with Drupal to the user guide. If we think that's a place we can capture some of the learner to skilled audience.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

That is a good idea to think about other pages on drupal.org to promote the User guide on... Some ideas of places the User Guide could be displayed or more prominently displayed (in no particular order):

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

User miro_dietiker suggested on #2832033: User guide not linked at Understanding Drupal 8 , which I just marked as a duplicate of this issue, that we should put a link to the User Guide on
https://www.drupal.org/docs/8/understanding-drupal