As a part of #2533684: Create 'Documentation' Section we are getting ready to migrate existing documentation into the new section.

During the migration:

  • the content type for documentation will be changed from 'book page' to 'documentation page' and 'documentation guide'
  • documentation will be split by major Drupal version (#2587331: Split documentation per Drupal version)
  • documentation will be reorganized into a new structure (#2744915: Define new structure for documentation)
  • book outline will be replaced with 'guides' system, where guide is a collection of documentation pages with own menu and maintainer(s), who have additional permissions to take care of the content inside of the guide

We will start by migrating 'generic' documentation, such as Understanding Drupal, Structure guide, etc. Documentation for contributed projects will follow in a couple of weeks.

Progress:

  • Understanding Drupal
  • Installation Guide
  • Administration & Security Guide
  • Structure Guide
  • Multilingual Guide
  • Mobile Guide
  • Theming Guide
  • Develop for Drupal
  • Site Building Guide: contributed projects documentation

How to help

If you'd like to help during and after migration, sign up to maintain specific part of the documentation over at #2682083: Recruiting guide maintainers for documentation

Information for contributed project maintainers

If documentation for your project exists somewhere in Site Building Guide or any other documentation book, we will create a new documentation guide, and migrate existing docs into it. If you are project maintainer, you will be added as a guide maintainer, so that you could modify guide, its menu, its contents, add other guide maintainers, etc.

Please be prepared to spend a bit of time in the next few weeks modifying your documentation post-migration. If there is specific time before/after which you want us to migrate documentation for your project, please let us know in the comments.

NOTE: Existing order of pages set via Book outline will be lost during migration. You will have to rearrange menu of your new documentation guide to set desired order of the pages.

The hierarchy of the pages inside of the guide is flat, which means there are no 'child' pages, all of them are on the same level inside of the guide. We strongly encourage you to merge pages together, and have less but longer pages in your guide.

Comments

tvn created an issue. See original summary.

tvn’s picture

Issue summary: View changes
tvn’s picture

Issue summary: View changes
tvn’s picture

Issue summary: View changes
tvn’s picture

Issue summary: View changes
tvn’s picture

Issue summary: View changes
saurabh.dhariwal’s picture

Issue summary: View changes
gisle’s picture

The old user contributed documentation was a Wiki and it was very simple to correct or add missing documentation.

I've looked at the new documentation pages that are being rolled out, and it looks like this is no longer the case. Instead, each page is assigned a "maintainer" and there is a button to "discuss".

If this how you plan things to stay, I fear that this will not be sustainable. Some pages are bound to become abandoned as maintainers lose interest or just move on.

When this happens to projects, there is both a temporary fix (patches posted to the project's issue queue), and a procedure for repairing the situation.

If the user contributed documentation is no longer going to be a Wiki, how are you going to deal with abandoned documentation pages?

gisle’s picture

As a part of #2533684: Create 'Documentation' Section we are getting ready to migrate existing documentation into the new section.

It also looks like you're removing the old user created documentation pages.

There is two problems with this approach:

  1. The documentation pages was very much interlinked. As you remove pages, these links go stale.
  2. The Wiki pages was copyedited by a multiple of individual users over time, and information was added to have specific information in place to cater for the needs for miscellaneouscommunity activities (e.g. Project Applications and LWG to name just two such activities I know about). The individual maintainers that now is in charge of the new pages cannot possibly know about all these activities and what they require from the documentation, and will probably delete a lot of important information in the process because they do not understand its relevance or significance.

By all means - create all the new pages you want to create, but please stop removing the old pages until you understand what they're used for and from where they are linked to.

tvn’s picture

re: #8 - documentation will stay a 'wiki', as in pages will be editable by any user as they are now. Permissions are restricted at this moment while we migrate initial pages and test that migration script and the new content types work the way we want them to. Permissions to be edit will be opened up shortly, definitely before we migrate bigger documentation books.

Each page is not assigned a maintainer, only 'guides' - collection of pages on specific topic - are. Issue linked at the top of the issue summary and various child/related issues provide more information about the functionality we are moving towards and why.

Re: #9 - we are not removing pages. Migration script changes the content type of the node, but the author/history of revisions/comments/url are all preserved. That said during the audit of documentation pages we did identify *obviously* outdate pages, empty pages, etc. which will not be migrated into the new system. Those pages will be kept as book pages until the migration is finished and people had a chance to highlight if something relevant is missing and should indeed be migrated.

tvn’s picture

Issue summary: View changes

Status update: we kicked off migration with docs about Drupal.org, to test out migration script and fix any potential bugs before we start migrating documentation about Drupal. Found a few minor things and fixed them. I should start migrating 'Understanding Drupal' guide soon-ish.

tvn’s picture

Issue summary: View changes

Understanding Drupal book now done. Content from it went into the two new guides:
https://www.drupal.org/docs/7/understanding-drupal
https://www.drupal.org/docs/7/choosing-drupal-version

D8 versions of those need to be created #2774809: Write documentation for Drupal 8

joachim’s picture

Is there an issue for migrating the contrib modules documentation?

I am very concerned about the migration discarding book hierarchy data. There are many modules where this is a vital part of the content, and losing it will mean a lot of manual work to restore it. Eg Feeds https://www.drupal.org/node/622696, and Flag https://www.drupal.org/documentation/modules/flag, to pick just two modules at random.

tvn’s picture

There is not a separate issue for contrib, this one covers all migration. We are not migrating contrib docs yet.

Regarding the hierarchy, flat hierarchy does not mean that all of the pages about a module will be in a single guide. We will create sub-guides to preserve hierarchy whenever makes sense. E.g. in the Feeds example there can be an overall Feeds documentation guide, with sub-guides: The site builder's guide to Feeds, The developer's guide to Feeds, Contributed plugin modules for Feeds.

tvn’s picture

Issue summary: View changes

Updating status. Installation guide is done. Admin and security guide is in progress.

andypost’s picture

Having so big fonts require to make width to be wider

It's really hard to read https://www.drupal.org/docs/8/modules/features

joachim’s picture

> Regarding the hierarchy, flat hierarchy does not mean that all of the pages about a module will be in a single guide. We will create sub-guides to preserve hierarchy whenever makes sense. E.g. in the Feeds example there can be an overall Feeds documentation guide, with sub-guides: The site builder's guide to Feeds, The developer's guide to Feeds, Contributed plugin modules for Feeds.

Have you had a look at the Flag documentation? That nests quite deep. I'm really not happy about the prospect of that structure being lost.

Is there an issue where the contrib module docs migration is being worked out?

Markéta’s picture

Markéta’s picture

darol100’s picture

Is there an issue where the contrib module docs migration is being worked out?

I have the same question.

tvn’s picture

Quoting from my comment #14:

There is not a separate issue for contrib, this one covers all migration. We are not migrating contrib docs yet.

darol100’s picture

oopss... I should have read everything.

Thank you

tvn’s picture

Issue summary: View changes

Updating migration progress.

joachim’s picture

Please don't migrate docs for Flag until the matter of what to do with the deep hierarchy is resolved.

mjhoy’s picture

Installation guide is done

Hi. I just wandered over to the Drupal 8 install docs, thinking I would test it out today, and there's hardly anything there. What am I missing?

https://www.drupal.org/docs/8/install

tvn’s picture

Most of existing content in the Installation guide was Drupal 7, content for D8 still needs to be written.

mjhoy’s picture

Isn't the content written already? Why not just link to https://api.drupal.org/api/drupal/core%21INSTALL.txt/8.1.x rather than have a confusing, broken-looking documentation site?

klausi’s picture

gisle’s picture

The "comment" feature of the new documentation has a pretty brain-damaged text format.

  • It appears to be a plain text format that doesn't convert line breaks to <p> markup.
  • It renders safe HTML (such as <p> and <a ...>as plain text.
  • It doesn't understand links.

For an example of the brain-damage, see my comment here.

joachim’s picture

I assume no links is to prevent spam, but we really need to be able to link to other docs pages, issues, and API pages.

gisle’s picture

I assume no links is to prevent spam

We have the "Confirmed" user role to prevent non-trusted users from abusing their account here (to post spam and other unappreciated junk). I assume that anyone with the "Confirmed" user role can (and should) be trusted with posting links?

JurriaanRoelofs’s picture

Updating status. Installation guide is done. Admin and security guide is in progres

I wanted to link some clients in need of support to the "updating modules/themes" documentation but it's missing any information about the update manager:
https://www.drupal.org/documentation/modules/update
I don't want to make my clients bother with FTP and finding passwords etc. because Drupal has this great solution for updating non-interactively using the update manager, is there any reason it's excluded in the official docs or is it something we can add there?

link in old docs: https://www.drupal.org/documentation/modules/update

pukku’s picture

According to the summary at the top, the installation guide has been migrated. However, when I try to view the installation system requirements, it's basically empty. What version of SQLite is compatible with Drupal 8?

andypost’s picture

requirements redirected to https://www.drupal.org/docs/7/system-requirements/overview
>SQLite 3.7.11 or higher

tvn’s picture

Regarding the comments, we are aware of the problem and plan to address it in the next week or so. Here is the issue #2817225: Stop stripping newlines and other formatting from comments on documentation pages.

I wanted to link some clients in need of support to the "updating modules/themes" documentation but it's missing any information about the update manager.

Which guide/page were you linking to that is missing this info?
There is no reason to exclude it, https://www.drupal.org/documentation/modules/update just hasn't been migrated into the new system yet.

According to the summary at the top, the installation guide has been migrated. However, when I try to view the installation system requirements, it's basically empty.

Most of the existing documentation content is about Drupal 7 and hence has been migrated into https://www.drupal.org/docs/7. Drupal 8 documentation located at https://www.drupal.org/docs/8 is still far from complete. Feel free to add information when you see it missing in D8 docs. Here is related issue #2774809: Write documentation for Drupal 8.

Christopher James Francis Rodgers’s picture

 

Notice to drupal.org documentation creators

Do not link to any of the new Documentation pages, using the textual 'friendly URL' in the address-bar. That URL will change every time someone decides to change the page's 'title'.

If you want to link to one of the new drupal.org documentation pages, login to drupal.org, (or register, and confirm your registration in your eMail), click the "Edit" button for the page you want to link to.

Remove the "/edit" portion of the URL that you will then see in your browser's address-bar for that page.

The permanent URL that you must now use to link to any new drupal.org documentation page will be similar to https://www.drupal.org/node/###### with numerals instead of '######'.

---

"Though a bit ranty," admittedly, that issue is here [2824170]

 

tvn’s picture

Issue summary: View changes

We are currently migrating core modules documentation from the Site Building guide.

slashrsm’s picture

Drupal 8 media team has been maintaining "D8 media guide" on GitHub: https://github.com/drupal-media/d8-guide. The reason for that is the fact that having docs in some common format (Markdown in our case, but not limited to that) makes it easily portable and re-usable. Having it in a git repo is also beneficial since you have it versioned, one can easily clone and compile it in full locally, we get to use same contribution workflows as we're used to in our every-day life, ...

But there are also downsides (like always:)). Having it on GitHub/GitBooks and not on drupal.org causes big discover-ability problem, which we would like to solve. However, we wouldn't like to move away from current format.

I noticed that D8 user guide uses AsciiDoc. Would it be possible to do something similar for Media guide? Are there any APIs that would allow us to compile and publish changes to it automatically?

drumm’s picture

The compiled user guide still has some rough edges and does take some time for us to update. For example, #2831856: Deploy changes to User Guide modules etc.. The planned editorial process there is to update on Drupal.org when a tag is pushed. It hasn’t been fully automated yet. I wouldn’t want to add more guides like this.

If the Media guide fits into a chapter of the existing user guide project, that would work nicely.

Joachim Namyslo’s picture

Guess this may be the wrong place to discuss. But I used the documentation now from a newbee perspective to start learning codeing for Drupal By using this as a visitor of Drupal org I find it somewhat confusing that the documentation mixes d7 and d8 in the navigation trainl An example is:

https://www.drupal.org/docs/8/creating-custom-modules/naming-and-placing...

There is a link to https://drupal.org/node/1056468

So if you follow this

After changing the page the navigation trail on the right is changing and you see some d7 related things as well. I know that Drupal's docs must be extremely massive but this is a confusing behavior. Where is the place to suggest a better navigation trail? Is there any none else seeing my point or is this just a silly newbie opinion?

tvn’s picture

@dinmikkith Please use 'Discuss' tab of the page in question to suggest improvements. For this particular case it seems the first page you mention simply needs to be updated. The link should go to Drupal 8 version of the documentation page 'Show all errors while developing' instead of Drupal 7.

SebCorbin’s picture

Don't know where to put this issue, but there's a problem with code block formatting on this page https://www.drupal.org/docs/7/api/render-arrays/render-arrays-overview#c...

drumm’s picture

I fixed up the markup there (using CKEditor) and added a note about this to #2741227-30: Enable CKEditor for more content types.

gisle’s picture

I am reporting this documentation page: https://www.drupal.org/drupalorg/style-guide/grid .

(I am not allowed to edit the page, and there is no "discuss" tab or "report errors" link.)

The page refers to a "design grid" with no context and explanation about how this "design grid" is part of Drupal. Two support questions and one bug report:

  1. Where is the css that implements the "container-x" and "grid-y" classes used in the examples?"
  2. Where am I supposed to put this markup?
  3. The HTML-syntax is wong (no end angle bracket in some mark-up, and the end </div> for the container looks like it is the wrong place) and is not even obvious to me how to fix it.

This is the landing page arrived at after googling "drupal using 12 column grid". We need make sure doc pages are self-contained because every doc page is a landing page for Google. In this case, navigating up or sideways did not help me finding out how to use a 12 column grid when theming a Drupal site.

jcnventura’s picture

Just wanted to note that the PHP requirements for D8 can't yet be found in the /8/ section, and are only found in the docs for D7.

tvn’s picture

@gisle This issue is about migrating documentation into the new system. Please open separate issues in the Documentation queue for other questions/reports.

@jcnventura Please feel free to create a new page in the appropriate D8 guide and port the content from D7 docs.

gisle’s picture

tvn wrote:

@gisle This issue is about migrating documentation into the new system. Please open separate issues in the Documentation queue for other questions/reports.

And pages in the new documentation system are broken. AFAIK, there are no such problems with the pages in the existing document system. I think you should have some sort of QA after a page has been migrated, rather then having them reported one by one.

As noted in #44 I am not allowed to edit the page, and there is no "discuss" tab or "report errors" link.

tvn’s picture

As noted in #44 I am not allowed to edit the page, and there is no "discuss" tab or "report errors" link.

That is because the page you are talking about is not a documentation. You are looking at the Drupal.org style guide, and page that describes grid of the Drupal.org theme. If you want to suggest improvements to the style guide, please open a new issue.

gisle’s picture

That is because the page you are talking about is not a documentation.

Well, it sure looks like documentation to me (it even uses the same distinctive Ubuntu Google font and the same layout as the rest of the Drupal.org documentation - and unlike the sans-serif font stack with Verdana, etc. that is used on the parts of Drupal.org that are not documentation. (I don't think I am the only designer that uses visual clues like fonts to classify content.)

But from your kind comment, I now understand that this page really is something different™. And also that it is the the user's responsibility to know the difference.

If you want to suggest improvements to the style guide …

No, I don't - not any more.

Reporting documentation issues at Drupal.org apparently requires one to understand how the cabal that manages documentation has divided the site up in twisty little documentation sub-sites, all different. This is a game I don't have the time to play.

TR’s picture

The issue summary says:

Information for contributed project maintainers

If documentation for your project exists somewhere in Site Building Guide or any other documentation book, we will create a new documentation guide, and migrate existing docs into it. If you are project maintainer, you will be added as a guide maintainer, so that you could modify guide, its menu, its contents, add other guide maintainers, etc.

Please be prepared to spend a bit of time in the next few weeks modifying your documentation post-migration. If there is specific time before/after which you want us to migrate documentation for your project, please let us know in the comments.

Please clarify, you have NOT migrated my documentation (Ubercart), and if I try to migrate the documentation myself using the link (https://www.drupal.org/migrate/documentation/159733) on my bookpage (https://www.drupal.org/documentation/modules/ubercart), I receive an error message:

Migration cancelled. You tried to migrate over 30 child nodes. Usually a guide consists of a smaller number of pages. To prevent possible mistakes, please select a smaller sub-set of book pages for migration at a time.

There is NO information or documentation about how to "select a smaller sub-set of book pages for migration" - there is only the link on my main book page that says to click and the migration will happen.

Ubercart is a major module that has been around for 10 years. It has tens of thousands of users and hundreds of book pages of documentation at https://www.drupal.org/documentation/modules/ubercart. This whole migration business seems to be focused on minor, small projects and has really ignored the needs of maintainers like me who support tens of thousands of users and several dozen projects.

It would have been really nice if you could have informed project maintainers like me when you changed the documentation system, and it would have been even nicer if you had migrated my documentation yourself after making this change - leaving it to me to discover some months later and try to migrate it myself is a little anti-social. Throwing an error because I have too much documentation is just ridiculous.

drumm’s picture

TR - you can migrate smaller batches of pages by starting at a point deeper in the book hierarchy, such as https://www.drupal.org/node/1312862.

The new documentation pages have some structural differences which don’t automate well. Such as the summary field - the migration tries picking out the first few words, but there’s a good chance that’s not a great summary. Each page should get some review by a person as it is migrated, unfortunately that does add up for more-documented projects.