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 DrupalInstallation GuideAdministration & Security GuideStructure GuideMultilingual GuideMobile GuideTheming GuideDevelop 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
Comment #2
tvn CreditAttribution: tvn at Drupal Association commentedComment #3
tvn CreditAttribution: tvn at Drupal Association commentedComment #4
tvn CreditAttribution: tvn at Drupal Association commentedComment #5
tvn CreditAttribution: tvn at Drupal Association commentedComment #6
tvn CreditAttribution: tvn at Drupal Association commentedComment #7
saurabh.dhariwal CreditAttribution: saurabh.dhariwal at AddWeb Solution Pvt. Ltd. commentedComment #8
gisle CreditAttribution: gisle at Hannemyr Nye Medier AS commentedThe 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?
Comment #9
gisle CreditAttribution: gisle at Hannemyr Nye Medier AS commentedIt also looks like you're removing the old user created documentation pages.
There is two problems with this approach:
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.
Comment #10
tvn CreditAttribution: tvn at Drupal Association commentedre: #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.
Comment #11
tvn CreditAttribution: tvn at Drupal Association commentedStatus 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.
Comment #12
tvn CreditAttribution: tvn at Drupal Association commentedUnderstanding 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
Comment #13
joachim CreditAttribution: joachim commentedIs 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.
Comment #14
tvn CreditAttribution: tvn at Drupal Association commentedThere 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.
Comment #15
tvn CreditAttribution: tvn at Drupal Association commentedUpdating status. Installation guide is done. Admin and security guide is in progress.
Comment #16
andypost CreditAttribution: andypost as a volunteer and at Skilld commentedHaving so big fonts require to make width to be wider
It's really hard to read https://www.drupal.org/docs/8/modules/features
Comment #17
joachim CreditAttribution: joachim commented> 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?
Comment #18
Markéta CreditAttribution: Markéta as a volunteer and commentedComment #19
Markéta CreditAttribution: Markéta as a volunteer and commentedComment #20
darol100 CreditAttribution: darol100 as a volunteer and at DarrylNorris commentedI have the same question.
Comment #21
tvn CreditAttribution: tvn at Drupal Association commentedQuoting from my comment #14:
Comment #22
darol100 CreditAttribution: darol100 as a volunteer and at DarrylNorris commentedoopss... I should have read everything.
Thank you
Comment #23
tvn CreditAttribution: tvn at Drupal Association commentedUpdating migration progress.
Comment #24
joachim CreditAttribution: joachim commentedPlease don't migrate docs for Flag until the matter of what to do with the deep hierarchy is resolved.
Comment #25
mjhoy CreditAttribution: mjhoy commentedHi. 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
Comment #26
tvn CreditAttribution: tvn at Drupal Association commentedMost of existing content in the Installation guide was Drupal 7, content for D8 still needs to be written.
Comment #27
mjhoy CreditAttribution: mjhoy commentedIsn'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?
Comment #28
klausi CreditAttribution: klausi at epiqo commentedOpened #2811365: Code blocks should be able to show lines with 80 characters and #2811359: WYSIWYG editor breaks code formatting.
Comment #29
gisle CreditAttribution: gisle at Hannemyr Nye Medier AS commentedThe "comment" feature of the new documentation has a pretty brain-damaged text format.
<p>
markup.<p>
and<a ...>
as plain text.For an example of the brain-damage, see my comment here.
Comment #30
joachim CreditAttribution: joachim commentedI assume no links is to prevent spam, but we really need to be able to link to other docs pages, issues, and API pages.
Comment #31
gisle CreditAttribution: gisle at Hannemyr Nye Medier AS commentedWe 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?
Comment #32
JurriaanRoelofs CreditAttribution: JurriaanRoelofs commentedI 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
Comment #33
pukku CreditAttribution: pukku commentedAccording 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?
Comment #34
andypost CreditAttribution: andypost as a volunteer and at Skilld commentedrequirements redirected to https://www.drupal.org/docs/7/system-requirements/overview
>SQLite 3.7.11 or higher
Comment #35
tvn CreditAttribution: tvn at Drupal Association commentedRegarding 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.
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.
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.
Comment #36
Christopher James Francis Rodgers CreditAttribution: Christopher James Francis Rodgers commentedNotice 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]
Comment #37
tvn CreditAttribution: tvn at Drupal Association commentedWe are currently migrating core modules documentation from the Site Building guide.