Drupal 8 Docs: Some Thoughts

With feature freeze for Drupal 8 approaching quickly, I thought it might be a good time to raise the thorny subject of what can/should/will/might be done to update the core documentation on d.o and the online help. At a bare minimum, it would be useful to at least articulate the scope of the work and perhaps identify priorities and challenges.

Another closely related question is how d.o.'s upgrade to D7 and the GSOC work on the help system might impact the approach to D8 documentation. This might significantly affect the way content is handled and how much work can be accomplished by a tiny and highly transient group of contributors. That's a topic for another post but if anyone has information or opinions, please post in the comments!

Eventually it would be nice to work up a comprehensive doc plan that covers everything in detail but to get the ball rolling, here's a first crack at articulating the scope of documentation impacts, broken out by guide. This is based on a quick initial scan and is just intended to get the conversation started (if there's anyone out there to converse with):

• Understanding Drupal - Probably no significant changes (but needs to be checked)
• Installation Guide - system requirements has already been updated, installing contributed modules is a little different in D8. Because the directory structure is different in D8, various parts of the installation guide will need to be updated. Also the install script itself will be different. Looks like there might be lots of stuff under the "Additional Topics" heading (which should be changed to something less vague). Do we need a separate "Installing Drupal 8 Section"?
• Administration and Security Guide - We have a 'Getting Started with Drupal 7 Administration' section and will probably need a similar section for D8 (or rethink the concept of that section). The security section I'm guessing will be largely unchanged but that assumption needs to be validated. There's a "Managing Configuration in Drupal 8" stub which needs to be fleshed out. I believe there are some big changes in this area so it might be a bit of work. A big priority in this guide will be in the 'Upgrading From Previous Version Section' where there absolutely must be an 'Upgrading From 7 to 8' page. The rest of the guide needs to be evaluated for changes.
• Structure Guide - Now that Views is in core, this section will become a priority. A lot of conceptual/structural stuff seems to be changing (i.e. blocks) so there's probably some significant updates needed throughout this guide.
• Site Building Guide - Much of this guide is based on contrib modules but there are definitely chunks that need updating like the list of core modules and various topics such as media handling
• Multilingual Guide - Big changes now that Drupal 8 is supposed to be international out of the box.
• Theming Guide - More significant changes to theming in D8. I suspect that this will again be one of the biggest and thorniest guides to deal with. And probably we will again have the discussion of whether there should be version-specific Theming Guide and again I will say yes ... BUT ... we desperately need a way to reuse generic content across guides (as opposed to duplicating content in each guide which, in technical communication, is the equivalent of killing kittens).
• Mobile Guide - Looks relatively generic and contrib-focused but needs further analysis
• Develop for Drupal - There has been some ongoing work to update for D8 but there will probably be some fairly significant changes and new content. One priority might be a "Creating Drupal 8.x modules" section (to go with similar sections for 6 and 7)
• Everything else on d.o. - Most of the other guides, like FAQs, recipes, etc. are done on an ad hoc basis anyway, so are probably out of scope for this survey (and the API reference is a different world)
• Help - No idea what is planned for D8. Anybody want to jump in?

Thoughts? Comments? Please jump in