Why Drupal 8 documentation on drupal.org has two versions


If you are new to Drupal, and you have wisely decided to use Drupal 8 (D8) instead of Drupal 7 (D7), and if you are trying to find a clear step-by-step guide here at drupal.org (d.o) to achieve exactly what you want to do, (first of all, “Good luck,”) please be aware that Drupal 8 documentation is divided into two distinct sections.

Two separate Drupal 8 documentation sections:

  1. Drupal 8 documentation (Link opens in a new tab/window.)
  2. Drupal 8 User Guide (Link opens in a new tab/window.)

1.) Drupal 8 documentation

The ‘Drupal 8 documentation’ section was created in 2016 to organize and migrate all of the D8 pages from the old documentation section of d.o which had included D4, D5, D6, D7, and D8 information combined.

As with the old documentation, the new ‘Drupal 8 documentation’ is immediately editable by by you if you first register as a user on d.o.

The migration is not complete, and information is yet scattered across duplicate pages, and currently [2017.07.02] has pages that are still in the old documentation section, outside of the new D8 documentation section.

Your help is both needed and appreciated.

2.) Drupal 8 User Guide

The ‘Drupal 8 User Guide’ was created from scratch, and was designed to be more of an official guide, and a definitive guide, that can be easily and continually translated into any number of non-English languages.

You will not be able to edit the ‘Drupal 8 User Guide’ in real-time, though you can make suggestions for its improvement to the authority in command of it, or, if you are interested, you can also become a member of that team.

Here too, your help is both needed and appreciated.

Which guide you should start with

I can not answer that, since by all appearances to me, the documentation at d.o has all the appearances of being a war waged on two fronts.

I would like to think that the strictly moderated ‘Drupal 8 User Guide’ will eventually be a great place for users of all levels, from ‘absolute beginner’, through ‘code developer guru’, but that is not currently the case.

Be an unsung hero – One in a thousand

If you, like me, cherish daunting challenges, and welcome the prospect of helping with what I loosely, and comedic-ly, refer to as the ‘train wreck’ that the d.o documentation is…

And if you find pleasure knowing you have made contributions which help thousands of people, without a need for gratification from others…


To say that you would be ‘one in a thousand’ is not exactly accurate.

Technically, that figure is based on there being 2-1/2 million Drupal sites globally (Link opens in a new tab/window.), and reportedly less than an average of 200-monthly contributers to d.o documentation per a report I heard on a 2016 Drupalcon presentation at YouTube; and assumes that every single individual Drupal user manages 12 or 13 sites, which I doubt.

If you were to adopt the unsung role of being a d.o documentation contributor, a sorceress or sorcerer similar to the wizard in the ‘Wizard of OZ’ (You know: “Pay no attention to the man behind the curtain!”), then you, my dear friend, would more accurately be one in ten-thousand.


Note: Any corrections you would like to see made to the above, or additions you would like to see, I will incorporate above, assuming I yet live. Just comment below.

…or is it possible for you to edit the above yourself? If so, “Do it.”


Drupal version: 

Source: https://www.drupal.org/taxonomy/term/20/feed